If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/anthropics/claudes-c-compiler shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 2 active contributors
• CC0-1.0 licensed
• ⚠ Slowing — last commit 3mo ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live anthropics/claudes-c-compiler repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/anthropics/claudes-c-compiler.

What it runs against: a local clone of anthropics/claudes-c-compiler — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in anthropics/claudes-c-compiler | Confirms the artifact applies here, not a fork | | 2 | License is still CC0-1.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 121 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of anthropics/claudes-c-compiler. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/anthropics/claudes-c-compiler.git
#   cd claudes-c-compiler
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of anthropics/claudes-c-compiler and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "anthropics/claudes-c-compiler(\\.git)?\\b" \\
  && ok "origin remote is anthropics/claudes-c-compiler" \\
  || miss "origin remote is not anthropics/claudes-c-compiler (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(CC0-1\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"CC0-1\\.0\"" package.json 2>/dev/null) \\
  && ok "license is CC0-1.0" \\
  || miss "license drift — was CC0-1.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "DESIGN_DOC.md" \\
  && ok "DESIGN_DOC.md" \\
  || miss "missing critical file: DESIGN_DOC.md"
test -f "src/backend/README.md" \\
  && ok "src/backend/README.md" \\
  || miss "missing critical file: src/backend/README.md"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "src/backend/arm/codegen/mod.rs" \\
  && ok "src/backend/arm/codegen/mod.rs" \\
  || miss "missing critical file: src/backend/arm/codegen/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 121 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~91d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/anthropics/claudes-c-compiler"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Claude's C Compiler (CCC) is a zero-dependency C compiler written entirely in Rust that targets x86-64, i686, AArch64, and RISC-V 64-bit architectures, producing ELF executables. It implements a complete compiler pipeline from scratch—lexer, parser, SSA-based IR, optimizer, code generator, peephole optimizer, assembler, linker, and DWARF debug info—without relying on GCC or any external toolchain, and is capable of compiling a booting Linux kernel. Single monolithic Rust binary (src/main.rs) with five entry points (src/bin/ccc*.rs) that re-use the same core pipeline; architecture flows linearly: Lexer → Parser → Semantic Analysis → SSA IR generation → Optimization passes → Target-specific code generation (x86_64, x86_32, ARM, RISCV modules) → Assembler → Linker. The include/ directory contains intrinsic header stubs (AVX, NEON, etc.). No modular crate separation.

Systems programmers, kernel developers, and compiler researchers who need a portable C compiler for bare-metal and embedded development across multiple architectures without external dependencies; also educational for those learning compiler design from a real, production-scale implementation.

Experimental and AI-generated: the code was written entirely by Claude Opus 4.6 without interactive debugging or validation by humans. The README explicitly warns against using it for production—no external validation of correctness has been performed. The codebase is substantial (~8MB Rust), but represents a research artifact rather than a hardened compiler; commit activity and issue management are not visible in the provided metadata.

Very high risk for production use: (1) the entire codebase is unvalidated AI-generated code with no human review of correctness or security, (2) the README explicitly disclaims correctness and states it was only tested on Linux hosts—MacOS/Windows are untested, (3) the 30+ open tasks in current_tasks/ indicate known bugs across ARM assembly, x86 floating-point, macro substitution, and kernel-specific issues, (4) the compiler is fundamentally a research proof-of-concept, not a tested replacement for GCC/LLVM.

Active bug fixing on multiple fronts: current_tasks/ directory lists 15+ high-priority issues including ARM CASPAL instruction assembly, x86 i686 double parameter handling, RISC-V va_arg for long doubles, ARM global branch relocations, x86 floating-point precision for f128, and macro parameter substitution bugs. The ideas/ directory suggests ongoing research into register allocators, peephole optimization improvements, and compile-speed enhancements.

Check README for instructions.

Daily commands:

# Compile a C file and execute (x86-64)
./target/release/ccc -o myprogram myprogram.c
./myprogram

# Cross-compile for ARM64
./target/release/ccc-arm -o myprogram myprogram.c
qemu-aarch64 -L /usr/aarch64-linux-gnu ./myprogram

# Emit assembly only
./target/release/ccc -S myprogram.c

# Use as a drop-in replacement for GCC
CC=/path/to/ccc-x86 make
CC=/path/to/ccc-x86 ./configure

• src/main.rs — Entry point for the compiler; orchestrates frontend parsing, IR generation, optimization, and backend code generation across all architectures.
• DESIGN_DOC.md — Comprehensive architectural documentation explaining the compiler's design philosophy, IR structure, and optimization strategy; essential reading for understanding the codebase.
• src/backend/README.md — High-level overview of the backend subsystem architecture, detailing how code generation is organized across x86-64, i686, ARM, and RISC-V targets.
• Cargo.toml — Project metadata and feature flags; defines the dependency-free build and conditional GCC fallback behaviors critical to the compiler's philosophy.
• src/backend/arm/codegen/mod.rs — Central ARM code generation module that coordinates register allocation, instruction selection, and peephole optimization for the ARM backend.
• README.md — Project overview and caveats; clarifies that Claude Opus 4.6 wrote this compiler without human validation, essential context for understanding risk and limitations.

Add Support for a New Architecture Backend

1. Create a new binary entry point (e.g., src/bin/ccc_myarch.rs) that invokes the main compiler with the target architecture specified. (src/bin/ccc_myarch.rs)
2. Create a new backend directory structure mirroring ARM: src/backend/myarch/codegen/mod.rs for instruction selection, src/backend/myarch/assembler/mod.rs for encoding, and src/backend/myarch/linker/mod.rs for linking. (src/backend/myarch/codegen/mod.rs)
3. Implement the Codegen trait in codegen/mod.rs with architecture-specific lowering of IR operations to machine instructions; use peephole optimization modules (e.g., peephole.rs) for micro-optimizations. (src/backend/myarch/codegen/mod.rs)
4. Create instruction encoder modules in assembler/encoder/ (e.g., alu.rs, load_store.rs) following the ARM pattern, then implement Assembler to emit ELF via elf_writer.rs. (src/backend/myarch/assembler/encoder/mod.rs)

Add a New Compiler Intrinsic or Built-in Function

1. Add the intrinsic signature to the appropriate header file in include/ (e.g., include/x86intrin.h for x86 intrinsics or include/arm_neon.h for ARM NEON). (include/x86intrin.h)
2. In the relevant backend codegen module (e.g., src/backend/arm/codegen/intrinsics.rs), add a pattern match case that lowers the intrinsic call IR node to architecture-specific instructions. (src/backend/arm/codegen/intrinsics.rs)
3. If the intrinsic requires special calling conventions or register allocation (e.g., for SIMD), add handling in codegen/calls.rs or create a specialized lowering pass. (src/backend/arm/codegen/calls.rs)

Fix a Code Generation Bug

1. Add the issue description to current_tasks/fix_<issue_name>.txt as a tracking file; include minimal test case or symptom. (current_tasks/fix_<issue_name>.txt)
2. Identify the affected backend (x86, ARM, RISC-V) and locate the problematic codegen or peephole optimization logic (e.g., in src/backend/arm/codegen/alu.rs or peephole.rs). (src/backend/arm/codegen/<module>.rs)
3. Apply fixes to the codegen or peephole module; verify against test case. If the fix is widely applicable, consider adding it to the IR optimizer or common codegen infrastructure. (src/backend/arm/codegen/<module>.rs)

Optimize Code Generation for a Specific Pattern

1. Add optimization idea to ideas/ directory (e.g., ideas/optimize_<pattern>.txt) describing the optimization goal and expected performance improvement. (ideas/optimize_<pattern>.txt)
2. Implement a new peephole optimization pass in the target backend's peephole.rs (e.g., src/backend/arm/codegen/peephole.rs) that matches and rewrites specific instruction patterns. (src/backend/arm/codegen/peephole.rs)
3. Optionally, add higher-level IR-level optimizations by extending the frontend IR optimizer or adding passes in the appropriate backend codegen module (e.g., codegen/mod.rs). (src/backend/arm/codegen/mod.rs)

• Rust (2021 edition) — Memory-safe systems language with zero-cost abstractions; enables dependency-free implementation of complex compiler components without runtime overhead or garbage collection.
• SSA-based Intermediate Representation — Enables powerful compiler optimizations (dead code elimination, constant folding, loop unrolling) while providing a clean, architecture-agnostic representation between frontend and backends.
• Multi-backend architecture (x86-64, i686, ARM, RISC-V) — Allows single IR to target diverse instruction sets; backend modules decouple instruction selection and register allocation from language semantics.
• Hand-written assembler & linker — Achieves true zero-dependency compilation by generating ELF and applying relocations natively; avoids coupling to external toolchain (GCC, LLVM, binutils).
• Peephole optimization passes — Post-codegen pattern-based optimizations (redundant move elimination, branch simplification) provide low-effort high-value improvements on baseline code.

• Zero external dependencies (no GCC/LLVM/binutils required)
  • Why: Demonstrates that a full compiler toolchain can be built from scratch in a single language; enables portable, self-contained deployment.
  • Consequence: Substantially more engineering effort to implement assembler, linker, and ELF generation; less

Critical: This is unvalidated AI-generated code; do not trust it for production. Cross-compilation sysroots required: Compiling for ARM/RISC-V requires aarch64-linux-gnu-gcc, riscv64-linux-gnu-gcc, etc. installed on the host—the compiler has no fallback. Linux-only: The codebase assumes Linux ELF format and glibc/musl headers; MacOS/Windows are explicitly unsupported and untested. Known architectural gaps: The ideas/ directory reveals unimplemented features (full f128 support, structured error reporting, use-def chains, register allocator improvements). Test coverage opacity: No visible test suite or CI configuration in the file list—confidence in any target should be very low. Macro handling bugs: current_tasks/fix_macro_param_prefix_substitution.txt indicates preprocessor substitution is broken in edge cases.

• Static Single Assignment (SSA) IR — CCC uses SSA as its intermediate representation for optimization passes; understanding SSA form (each variable assigned once) is essential for modifying the optimizer or debugging code generation bugs
• Peephole Optimization — CCC implements target-specific peephole passes (e.g., instruction combining, dead code elimination) after code generation; this is where most codegen quality improvements happen
• ELF (Executable and Linkable Format) — CCC hand-implements ELF object file generation and linking; understanding ELF sections, symbols, relocations, and program headers is mandatory for the assembler and linker components
• Application Binary Interface (ABI) — Each target (x86-64, ARM64, RISC-V) has a distinct calling convention and parameter passing ABI; bugs in ABI compliance (like the i686 double parameter issue) cause crashes—understanding ABI is critical for fixing backend bugs
• DWARF Debug Information Format — CCC generates DWARF debug info from scratch; understanding DWARF sections (.debug_info, .debug_line, etc.) is needed if adding debugging features or fixing breakpoint issues
• Relocation and Symbol Resolution — The hand-written linker in src/linker.rs must resolve external symbol references and apply relocations (absolute, relative, GOT-based); ARM global branch relocation bugs indicate incomplete relocation logic
• Register Allocation — CCC's code generator assigns variables to registers; the ideas/register_allocator.txt file suggests the current allocator is suboptimal. Understanding graph coloring or linear scan allocation is needed for future improvements

• gcc-mirror/gcc — The production-grade reference C compiler implementing the same C standard; compare output and behavior for correctness validation
• llvm/llvm-project — Alternative compiler infrastructure with modular backends for x86/ARM/RISC-V; architectural inspiration for SSA IR and peephole optimization design
• bellard/tcc — Tiny C Compiler, a minimal self-hosting C compiler; predecessor in the space of dependency-free C compilation, though far less capable
• riscv/riscv-gnu-toolchain — Official RISC-V GCC toolchain providing cross-compilation sysroots and reference binaries for validating CCC's RISC-V backend output
• torvalds/linux — The Linux kernel that CCC claims to compile; use as the ultimate integration test for correctness across all architectures

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Implement comprehensive test suite for ARM assembler encoder modules

The ARM backend has multiple encoder submodules (bitfield.rs, compare_branch.rs, data_processing.rs, fp_scalar.rs, load_store.rs, neon.rs) but there is no visible test directory structure. Given that ARM has 4 open tasks in current_tasks/ related to ARM assembly correctness (caspal_instruction, global_branch_relocs, org_directive, quad_prel64_relocation), unit tests for each encoder module would prevent regressions and help validate fixes. This is especially critical since the ARM backend is a core feature of a dependency-free compiler.

• [ ] Create tests/ directory structure mirroring src/backend/arm/assembler/encoder/
• [ ] Add unit tests for src/backend/arm/assembler/encoder/bitfield.rs covering bit manipulation edge cases
• [ ] Add unit tests for src/backend/arm/assembler/encoder/load_store.rs covering address modes and relocations
• [ ] Add unit tests for src/backend/arm/assembler/encoder/compare_branch.rs testing branch offset calculations
• [ ] Add integration tests validating ARM ELF output against objdump/readelf output
• [ ] Document test expectations in src/backend/arm/README.md

Add GitHub Actions CI workflow for multi-target compilation verification

The repo supports 4 target architectures (x86-64, i686, ARM, RISC-V) with 4 separate binaries defined in Cargo.toml, but no visible CI configuration. The current_tasks/ folder shows 13 open bugs across different targets. A CI pipeline that compiles all 4 targets and runs basic smoke tests would catch regressions early. This is critical for a compiler where architecture-specific codegen bugs are common.

• [ ] Create .github/workflows/multi-target-build.yml that builds all 4 binaries (ccc-x86, ccc-arm, ccc-riscv, ccc-i686)
• [ ] Add workflow step to validate that each binary produces valid ELF files using readelf
• [ ] Add workflow step to compile a minimal C program (e.g., hello world) with each target binary
• [ ] Add workflow step to verify no compiler warnings in strict mode
• [ ] Document in BUILDING_LINUX.txt or new CI_TESTING.md how to replicate CI checks locally

Create structured test fixtures for kernel compilation scenarios

The repo includes BUILDING_LINUX.txt indicating it can compile a Linux kernel, and current_tasks/ mentions kernel-specific issues (fix_x86_standalone_kernel_link_errors.txt, fix_riscv_kernel_boot_hang.txt). However, there are no visible test fixtures or regression test suite for kernel-scale compilation. Creating minimal reproducible kernel test cases would help validate compiler correctness and catch performance regressions early.

• [ ] Create tests/fixtures/kernel/ directory with minimal bootable kernel compilation scenarios
• [ ] Add tests/fixtures/kernel/x86_bootloader.c - minimal x86 real-mode boot code fixture
• [ ] Add tests/fixtures/kernel/arm_boot_vectors.c - ARM boot vector table fixture
• [ ] Add tests/fixtures/kernel/riscv_boot_code.c - RISC-V boot code fixture
• [ ] Create tests/kernel_compilation_tests.rs with test functions that compile each fixture against all 4 targets
• [ ] Document kernel testing process in BUILDING_LINUX.txt with reference to test fixtures

• Add comprehensive test suite for x86-64 code generation: Create a test harness in tests/codegen/ that validates code generation for each arithmetic operation, function call ABI, and control flow structure against expected assembly. Start with the test_x86_64_simple_arithmetic.rs test comparing compiled output to reference GCC binaries.
• Document the SSA IR format with examples: The src/ir.rs module defines the intermediate representation but lacks inline documentation. Add rustdoc comments with concrete before/after IR examples (e.g., loop unrolling, constant folding) to help future contributors understand optimization opportunities.
• Implement fix for ARM CASPAL instruction assembly (listed in current_tasks/fix_arm_asm_caspal_instruction.txt): This is a known bug in ARM64 code generation; add the missing CASPAL encoding to src/codegen/arm64.rs and verify with a test case that compiles a program using atomic operations.
• Add RISC-V va_arg long_double struct handling (from current_tasks/fix_riscv_va_arg_long_double_struct.txt): The RISC-V backend's src/codegen/riscv64.rs is missing proper va_arg lowering for long double structs; implement the ABI-compliant parameter passing and add a test in tests/riscv_varargs.c.

This is an experimental compiler project written entirely by AI with no external security validation. The codebase explicitly discourages production use. Key risks include: (1) unvalidated custom implementations of complex systems (linker, assembler, ELF writer), (2) numerous unresolved architectural tasks and bugs, (3) lack of comprehensive input validation framework in parsers, and (4) inline assembly and intrinsics support without clear security boundaries. The project is suitable only for research and educational purposes. Production use is not recommended without extensive security auditing, fuzzing, and formal verification of critical components.

• Medium · Incomplete/Unmaintained Codebase with Known Issues — Repository root, current_tasks/, README.md. The repository contains numerous unresolved tasks and ideas files indicating incomplete compiler implementation. The README explicitly states: 'I do not recommend you use this code! None of it has been validated for correctness.' This suggests the codebase has not undergone security review or correctness validation. Multiple critical architecture tasks remain in current_tasks/ (ARM ASM issues, x86 kernel link errors, macro parameter substitution bugs, RISC-V VA_ARG issues). Fix: Do not use this compiler in production. Conduct comprehensive security audit and correctness validation before any production deployment. Complete all outstanding items in current_tasks/.
• Medium · Linker Implementation Without External Validation — src/backend/*/assembler/elf_writer.rs. The project implements a custom linker from scratch without external toolchain dependencies. Custom linker implementations are complex and prone to vulnerabilities (buffer overflows, improper validation of ELF structures, relocation handling bugs). The file structure shows incomplete ELF writer implementations across multiple backends. Fix: Implement comprehensive fuzzing of ELF parsing and generation. Add strict bounds checking and validation for all ELF structure parsing. Consider formal verification for relocation logic.
• Medium · Custom Assembler Parser Without Input Validation Framework — src/backend/arm/assembler/parser.rs, src/backend/*/assembler/parser.rs. The codebase contains custom assembly parsers (src/backend/*/assembler/parser.rs) with no visible input validation infrastructure. Malformed inline assembly or crafted assembly input could trigger parsing errors, panics, or undefined behavior. Fix: Implement comprehensive input validation and sanitization for all assembly parser inputs. Add fuzz testing. Use panic-safe error handling with proper recovery mechanisms. Never panic on malformed user input.
• Low · Inline Assembly Support Without Clear Sandbox — src/backend/*/codegen/inline_asm.rs. Multiple inline_asm.rs files indicate support for inline assembly (src/backend/arm/codegen/inline_asm.rs, etc.). Inline assembly capabilities can bypass type safety and memory safety guarantees. Without clear sandboxing, malicious inline assembly could compromise the generated code. Fix: Document all inline assembly restrictions and security model clearly. Implement whitelist-based validation of inline assembly patterns. Consider warning users about the security implications of inline assembly features.
• Low · Intrinsics Implementation Without Standardization — src/backend/*/codegen/intrinsics.rs. Custom intrinsics implementations across multiple backends (intrinsics.rs files) without clear documentation of security properties. SIMD and low-level intrinsics can have platform-specific side effects and timing properties. Fix: Document all intrinsic implementations and their security properties. Add tests for side-channel resistance where applicable. Validate intrinsic behavior against official specifications.
• Low · GCC Fallback Features Enable External Tool Dependency — Cargo.toml, features section. The Cargo.toml features enable GCC as a fallback linker/assembler (gcc_linker, gcc_assembler, gcc_m16). While marked as optional, these features undermine the 'zero external dependencies' claim and introduce supply chain risk if GCC is compromised or misconfigured. Fix: Disable GCC fallback features by default. If GCC fallback is used, implement strict subprocess sandboxing and validation of GCC output. Warn users prominently about the security implications.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.