AST-based patcher for customizing the Claude Code CLI

cc-enhanced extracts the JavaScript bundle embedded in the Claude Code native binary, applies 34 verifiable patches through Babel AST traversal, and repacks the result in place. Every patch is a self-contained module with an independent verifier; one failure does not take down the rest. Promotion uses atomic symlinks, so rollback is one command.

Use it to unlock capabilities the CLI ships with but does not expose, fix long-standing bugs (shell quoting and LSP fan-out), swap tool parameters for more ergonomic alternatives (bat-style ranges on Read, batched edits[] on Edit, output tails on Bash), and replace prompt fragments that steer the model toward better shell tooling.

flowchart LR
    Bin([native binary]) -->|unpack ELF| Js[cli.js]

    Js --> Str[string patches<br/>prompt text only]
    Str --> Ast

    subgraph Ast[combined AST pass]
        direction LR
        D[discover] --> M[mutate] --> F[finalize]
    end

    Ast --> Ver{{each patch<br/>verifier}}
    Ver -- all pass --> Sig[signature suffix]
    Ver -- any fail --> Abort([abort + report])
    Sig --> Repack[repack into ELF<br/>same byte length]
    Repack --> Swap[atomic symlink swap]
    Swap --> Active([active binary])
    Active -. mise run native:rollback .-> Swap

    classDef terminal fill:#1f2937,stroke:#111,color:#fff
    classDef fail fill:#7f1d1d,stroke:#450a0a,color:#fff
    class Bin,Active terminal
    class Abort fail

Prompt-only edits run first as string transforms. Everything structural shares a single Babel traversal (discover -> mutate -> finalize) over the 16 MB bundle, so every AST patch sees the same parse. Each patch ships its own verifier; one failure is reported and the rest still apply. The repacked JavaScript goes back into the ELF container at the exact original byte length, so nothing downstream of the bundle is disturbed.

bun install

# Fetch latest upstream, patch it, and promote the result to active.
mise run native:update

claude --version
# <current> (Claude Code; patched: shell-quote-fix, bash-prompt, ..., signature)

mise run status
# Shows current, previous, and cached versions.

Rollback is a symlink swap, not a reinstall. mise run native:rollback exchanges the current and previous pointers atomically; the prior build stays on disk until it rotates out of the cache.

flowchart LR
    Launcher["~/.local/bin/claude"] --> Current["versions/current"]
    Previous["versions/previous"]
    Current --> NewBuild[["build N<br/>patched current"]]
    Previous --> OldBuild[["build N-1<br/>patched previous"]]
    NewBuild <-. swap .-> OldBuild

    classDef sym fill:#0b2545,stroke:#0b2545,color:#fff
    classDef build fill:#1e293b,stroke:#0f172a,color:#e2e8f0
    class Launcher,Current,Previous sym
    class NewBuild,OldBuild build

Each patch has a short tag. Include or exclude any subset via environment variables:

CLAUDE_PATCHER_INCLUDE_TAGS=read-bat,limits,edit-extended mise run native:update
CLAUDE_PATCHER_EXCLUDE_TAGS=tools-off,agents-off           mise run native:update

Changes to built-in tools (Read, Edit, Bash, LSP, Task, MCP).

Runtime behavior, caching, memory, and configuration.

Prompt text sent to the model.

Which built-in agents and commands are exposed.

Terminal interface polish.

Do not set DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. They disable every server-side flag, including features this patcher relies on. Use the individual DISABLE_ERROR_REPORTING, DISABLE_AUTOUPDATER, and DISABLE_BUG_COMMAND switches instead.

mise run native:update                            # Fetch + patch + promote + verify
mise run native:update -- <channel-or-version>    # latest, next, stable, or X.Y.Z
mise run native:update -- --dry-run               # Preview without promoting
mise run native:fetch-patch -- <version> --dry-run
mise run native:promote -- <build-path>           # Promote an already-patched cached build
mise run native:rollback                          # Swap current and previous symlinks
mise run status                                   # Show current, previous, cached
mise run native:pull -- <version>                 # Fetch upstream + extract clean JS to versions_clean/<version>/cli.js
mise run native:unpack-current -- <out>           # Extract patched JS from the currently-promoted binary (auto-detects via PATH)
mise run native:unpack -- <bin> <out>             # Extract embedded JS from any native binary
mise run verify:patches                           # Typecheck + lint + native dry-run + prompt drift
mise run verify:patches:matrix                    # Dry-run patches against latest clean cli.js
VERIFY_PATCHES_MATRIX_SCOPE=all mise run verify:patches:matrix
mise run verify:anchors -- <patched-cli> <clean-cli>
mise run verify:prompt-surfaces -- <export-dir>
mise run verify:prompt-drift -- <export-dir> --prompt-drift-baseline <baseline.json>
mise run prompts:export                           # Export prompt artifacts from promoted binary
mise run prompts:export -- <version> --output-dir /tmp/prompts-<version>
mise run prompts:drift-baseline -- <baseline.json> <export-dir> --prompt-drift-version <version>
bun run prompts:compare <vanilla-export> <patched-export> /etc/claude-code
bun run inspect search versions_clean/<version>/cli.js "Read" --field string --object
bun run inspect prompts versions_clean/<version>/cli.js "Command sandbox"
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js
bun run diff -- matrix versions_clean/<v1>/cli.js versions_clean/<v2>/cli.js versions_clean/<v3>/cli.js
bun run cli --list                                   # List available patches
bun run test                                      # Run the test suite (pinned to --parallel=1)

mise run patch is intentionally disabled; it exists only to redirect to native:update. package.json is the canonical alias table, and mise.toml is kept as a thin task index that calls those aliases. Use mise run <task> -- ... to pass versions, paths, or flags through to the underlying Bun alias. Non-trivial workflow logic lives in TypeScript, especially scripts/verify-patches.ts. See mise.toml for the task list and bun run cli --help for CLI flags.

Prompt exports are generated from cli.js bundles extracted from native builds or from the legacy npm package. That keeps the installed artifact as the truth while still making prompt drift reviewable as Markdown and JSON artifacts.

mise run prompts:export -- current
mise run prompts:export -- <version> --output-dir /tmp/prompts-<version>
mise run prompts:export -- versions_clean/<version>/cli.js --label <version>-check \
  --output-dir /tmp/prompts-<version>-check --max-uncategorized 200
mise run prompts:bundle -- current

Useful outputs:

verify:prompt-surfaces checks the curated patched surfaces and fails on dynamic prompt markers or unresolved helper placeholders such as ${value_...}, ${conditional(...), and ${...spread} unless that specific surface allows synthetic runtime placeholders. Broad corpus exports may still contain runtime-only placeholders; track those with manifest.quality.uncategorizedCount and use --max-uncategorized only when you want a hard drift budget.

verify:prompt-drift adds a path-based drift guard for the surfaces this patcher cares about most. prompt-surface-baseline.json is checked in and used by mise run verify:patches by default. Generate or refresh it only from a reviewed known-good patched export:

mise run prompts:drift-baseline -- prompt-surface-baseline.json exported-prompts/<version>_patched --prompt-drift-version <version>

Then compare future exports against it:

mise run verify:prompt-drift -- exported-prompts/<new-version>_patched --prompt-drift-baseline prompt-surface-baseline.json
mise run verify:patches

The baseline hashes normalized Markdown by exported path, not by content-derived prompt id. The drift watch list in src/verification/prompt-surface-rules.ts is authoritative for surfaces expected to exist in patched exports; optional surfaces removed by tools-off / agents-off stay in the broader review list but are not baseline requirements. If a new watched surface is added but the baseline has not been refreshed, verify:prompt-drift fails with baseline-missing-surface. If a watched hash changes, the update is not complete until the patch/exporter/rules are corrected or the baseline is refreshed after reviewing the new export as known-good. Edit the same file to choose which surfaces are watched, which optional surfaces are review-only, and which required/forbidden needles are enforced. Normalization ignores generated source_symbol values and renumbers synthetic ${value_...} / ${expr_...} placeholders so minifier churn does not create noisy drift.

prompts:compare is a human review report for comparing a vanilla prompt export, a patched prompt export, and the runtime /etc/claude-code policy layer. It reports file inventory deltas, manifest count changes, Unicode dash-style counts, review prompt-surface status (including optional surfaces intentionally removed by patching), exact-line overlap from /etc into the patched bundle export, and policy-term presence across both layers. The patched Unicode Dash Style counts should normally be zero; nonzero counts mean an exported prompt still demonstrates en dash or em dash prose style and should be reviewed before refreshing drift baselines.

bun run prompts:compare exported-prompts/<version> exported-prompts/<version>_patched /etc/claude-code
bun run prompts:compare exported-prompts/<version> exported-prompts/<version>_patched /etc/claude-code -- --json
bun run prompts:compare exported-prompts/<version> exported-prompts/<version>_patched /etc/claude-code -- --output /tmp/prompt-comparison.md

The inspector parses a bundle once per invocation and can run multiple search queries:

# Clean upstream JS for matcher development
mise run native:pull -- <version>                       # writes versions_clean/<version>/cli.js

# Currently-promoted patched JS for verifying a patch landed in the running build
mise run native:unpack-current /tmp/cli-patched.js

bun run inspect search versions_clean/<version>/cli.js "You are Claude Code" "Read a file" \
  --json --limit 5 --breadcrumb-depth 10 --object

bun run inspect search versions_clean/<version>/cli.js '^read$' --regex --ignore-case --field string
bun run inspect prompts versions_clean/<version>/cli.js "Command sandbox" --context 2

# Diff patched output against clean upstream
bun run diff -- versions_clean/<version>/cli.js /tmp/cli-patched.js

Use rg for quick literal string search in cli.js; use bun run inspect search when you need ranked AST matches, value-kind filters, nearest object context, byte span, breadcrumbs, scope, or JSON output. Do not use sg on cli.js.

bun run diff defaults to bundle-surface comparison. It is meant for upstream-to-upstream release review, where raw minified diffs are too noisy and prompt exports can miss new command wiring, telemetry surfaces, routes, or feature flags.

# Broad release report
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js --limit 20

# Narrow reports while triaging a build
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js --focus commands
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js --focus settings
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js --focus rewrites --markdown
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js --focus patches

# Cross-check prompt artifacts against added prompt-like bundle surfaces
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js \
  --prompt-export /tmp/prompts-<new> --focus prompts

# Cache extracted surfaces for repeated analysis
bun run diff -- versions_clean/<old>/cli.js versions_clean/<new>/cli.js --cache

# Compare a run of adjacent versions and summarize latest-only additions
bun run diff -- matrix \
  versions_clean/<v1>/cli.js \
  versions_clean/<v2>/cli.js \
  versions_clean/<v3>/cli.js \
  --markdown

The report groups high-signal additions and removals, reconstructs command candidates with nearby descriptions and flags, detects settings-write count changes, separates <system-reminder> prompt surfaces, detects prefix/text rewrites such as subsystem renames, highlights capability candidates, and estimates patch relevance from local patch anchors. For clean-vs-patched AST node comparison, call the legacy mode explicitly:

bun run diff -- ast versions_clean/<version>/cli.js /tmp/cli-patched.js

Optional bundle-diff.config.json settings keep local triage noise out of reports without hardcoding upstream internals:

{
  "ignoreTokens": ["placeholder"],
  "ignorePrefixes": ["[debug]"],
  "highSignalTokens": ["gateway", "purge"]
}

Each patch lives in src/patches/<tag>.ts beside a co-located <tag>.test.ts. New patches register in two places: the export barrel (src/patches/index.ts) and the metadata record (src/patch-metadata.ts). The /new-patch skill scaffolds the full set.

classDiagram
    class Patch {
        +string tag
        +string(code) code
        +astPasses(ast) PatchAstPass[]
        +postApply(ast, tags)
        +verify(code, ast) true|string
    }
    class PatchAstPass {
        +AstPassName pass
        +Visitor visitor
    }
    class AstPassName {
        <<enum>>
        discover
        mutate
        finalize
    }
    Patch "1" --> "*" PatchAstPass : produces
    PatchAstPass --> AstPassName
    note for Patch "string runs pre-parse.<br/>astPasses run in the combined traversal.<br/>verify gates promotion.<br/>postApply is for signature only."

Principles baked into the codebase:

• Find code by structure (string literals, property names), never by minified identifier names. They change every release.
• AST passes own all structural and behavioral change. String patches are reserved for prompt text.
• Verifiers target behavior and invariants, not expression shape.
• Target only the latest upstream. No backward-compatibility fallbacks.

Prompt policy is centralized in src/patches/prompt-policy.ts. Surface-specific patches still own their upstream anchors (bash-prompt, built-in-agent-prompt, claudemd-strong, memory-prompt-soften, session-guidance), but shared wording for Serena/LSP/ChunkHound/Probe/ast-grep routing lives in one module. Prompt-surface checks and drift watch paths are centralized in src/verification/prompt-surface-rules.ts, and tests build fixtures from those rules instead of duplicating long prompt text. Drift checks use fixed needles in src/verification/prompt-policy-contract.ts rather than importing the same generated strings, so accidental weakening of the shared policy still fails verification.

When a prompt patch changes live guidance, update both the patch verifier and the exported-surface rules. Current required live surfaces include the Bash/Read/REPL/tool-search surfaces, Explore/Plan agents, remote-planning reminders, system/sections/session-specific-guidance.md, and the dream-memory consolidation/pruning sections. Verify by exporting a patched bundle and running bun run verify:prompt-surfaces <export-dir>; bun run verify:patches does this for the native build path.

Current target: Claude Code 2.1.143. Tracks the latest upstream release and is updated with each upstream bump. Older versions are not maintained or tested; when upstream breaks a patch, it is fixed forward rather than kept backward-compatible. Run claude --version on the promoted binary to confirm the active target.

native:update accepts latest, next, stable, or an explicit X.Y.Z. The latest resolver cross-checks the native release bucket with the npm latest and next dist-tags so release promotion can follow npm when a new version appears there before the bucket alias moves.

• bun 1.3+ (managed via mise)
• mise for task-runner aliases; build and verification logic lives in Bun/TypeScript scripts
• Linux x86_64 (native ELF support is built in; other platforms require node-lief)
• A working Claude Code installation
• A local Claude Code policy file at /etc/claude-code/system-prompt.md, or set CLAUDE_CODE_APPEND_SYSTEM_PROMPT_FILE to the file you want auto-appended

Babel AST + generator over the 16 MB bundle is the heaviest part of the patcher. JSC (Bun's engine) sizes its heap dynamically, so no explicit flag is required; both direct bun src/index.ts ... and mise task invocations work.

The test suite uses bun test against the node:test API shim and is pinned to --parallel=1 because bun's shim mishandles concurrent file loads. Use bun run test (which already pins the flag) rather than raw bun test src/.

Several prompt patches intentionally route Claude Code away from the stock find/grep/cat/head/tail workflow. For the patched guidance to be useful, keep these command-line tools on PATH:

Recommended supporting tools for local development and verification:

The prompt patches use "available" deliberately. The patched CLI should still run without every MCP below, but the strongest behavior assumes these servers are configured where you expect code work to happen:

tools-off disables Claude Code's built-in Glob, Grep, WebSearch, WebFetch, and NotebookEdit surfaces. That is intentional. Keep the modern CLI tools and MCP replacements available, or exclude tools-off for a build that needs the stock tools.

This project is not affiliated with, endorsed by, or connected to Anthropic, PBC or any of its affiliates. "Claude" and "Claude Code" are trademarks of Anthropic, PBC. All other trademarks are the property of their respective owners.

This repository does not distribute Claude Code artifacts. Patches contain short text fragments used as match anchors for locating and replacing specific sections. The patcher operates exclusively on the end user's locally installed copy.

This tool modifies Claude Code, which may not be permitted under Anthropic's terms of service. Users are responsible for ensuring their use complies with all applicable terms and laws. The authors hold no liability for misuse, account actions, or damages resulting from this tool. Use at your own risk.

MIT