cc-enhanced

AST-based patcher for customizing the Claude Code CLI

cc-enhanced extracts the JavaScript bundle embedded in the Claude Code native binary, applies 45 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 and batched edits[] on Edit), and replace prompt fragments that steer the model toward better shell tooling.

[!NOTE]
This tool patches your local copy of the Claude Code binary. It does not distribute Claude Code binaries or npm packages. All modifications happen on your machine.

Subscription routing

The subscription routing guide documents
a pinned, reproducible two-launcher setup that keeps normal Claude Max sessions
direct while adding an isolated mixed-model launcher backed by Claude Max and
ChatGPT Pro subscriptions. It includes immutable source and artifact pins,
secure external credential storage, static and live verification, safe restart
gates, per-model context metadata, and workflow delegation policy.

How It Works

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 formatted 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.

Quick Start

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

Patches

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

Tooling

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

System

Runtime behavior, caching, memory, and configuration.

Prompt

Prompt text sent to the model.

Agent

Which built-in agents and commands are exposed.

UX

Terminal interface polish.

Metadata

Configuration

Patcher (build time)

Runtime (installed binary)

CLAUDE_CODE_BILLING_LABEL changes only the fallback text shown by the client when it cannot infer an account plan through its own authentication state. It does not select a credential or change how a provider charges a request. Scope it to the launcher that needs the clarification rather than placing it in shared Claude settings.

file-link-targets keeps stock file labels but rewrites WSL absolute-path hyperlink targets so Ctrl-clicks in Windows Terminal resolve outside WSL. The default wsl-file mode emits file://wsl.localhost/<distro>/.... Set CLAUDE_CODE_FILE_LINK_MODE=vscode for vscode://file..., vscode-remote for VS Code Remote WSL URLs, zed for zed://file..., file for explicit file URLs, or off/vanilla to keep stock file:///home/... links. CLAUDE_CODE_FILE_LINK_SCHEME accepts a custom URI scheme when CLAUDE_CODE_FILE_LINK_MODE is not one of the built-ins.

autoDreamEnabled is a Claude Code setting rather than an env var. When it is explicitly true, session-mem lets auto-dream run even if the server-side availability flag is off.

When gateway model discovery is enabled, Claude Code manages its model-capability cache under its configured cache directory. Do not edit that cache directly. Matching positive safe-integer max_input_tokens values take precedence over CLAUDE_CODE_MAX_CONTEXT_TOKENS; the environment value remains the startup, offline, and unknown-model fallback.

CLAUDE_CODE_CONFIGURED_MODEL_CATALOG is a JSON array such as [{"id":"provider/model","displayName":"Model","description":"Subscription route","maxInputTokens":258400,"maxOutputTokens":128000}]. IDs are trimmed, unique case-insensitively, and cannot replace native aliases or contain [1m]. Context windows must be positive safe integers up to 1M; output limits must be safe integers from 4096 through 1M. An exact configured match is available even when gateway discovery is off, but the catalog does not activate or consult unrelated cached gateway entries. Picker rows still obey stock availableModels policy, so include the canonical provider ID in that allowlist when one is configured.

CLAUDE_CODE_MODEL_ALIASES is alias indirection, not an allowlist bypass. Its value is a JSON object such as {"sol":"provider/model"}. Keys are trimmed and matched case-insensitively. The map fails fast when it is malformed, has distinct keys that collide after normalization, replaces a native alias or inherit, includes [1m], uses an empty or non-string target, or chains one alias to another. Exact duplicate JSON keys follow normal JSON.parse last-value semantics. Each resolved target still goes through stock model normalization and must be admitted by availableModels. Aliases work with --model, Agent model, Workflow agent({model}), agent frontmatter, resume, and explicit teammate selection. Aliases alone do not add /model rows; use CLAUDE_CODE_CONFIGURED_MODEL_CATALOG when a launch also needs friendly picker entries and per-model capability metadata.

CLAUDE_CODE_MODEL_PICKER_SESSION_ONLY is intended for launch-scoped wrappers that share a settings directory with normal Claude Code. With the variable present, /model changes the current session without overwriting the default used by future normal launches.

Alias resolution is runtime plumbing, not a routing policy. A launch-scoped system prompt can teach an orchestrator when to select a configured alias without changing normal launches that use the same patched binary. Forks continue to inherit the parent model, and CLAUDE_CODE_SUBAGENT_MODEL is unnecessary for per-call alias selection.

Do not set DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, or DISABLE_GROWTHBOOK. They disable feature-flag evaluation and the server-side flags that depend on it, including features this patcher relies on and the upstream Remote Control surface. Use the individual DISABLE_ERROR_REPORTING, DISABLE_AUTOUPDATER, and DISABLE_BUG_COMMAND switches instead.

CLI Reference

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 patch + 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 -- <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 Artifacts and Inspection

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 -- 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.

Bundle Diff and Release Triage

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"]
}

Extending

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 curated live surfaces include Bash/Read/REPL/tool-search/Edit tool prompts, Agent tool routing, Explore/Plan/worker/workflow-subagent/claude agent surfaces, remote-planning reminders, optional system/sections/schedule-remote-agents.md, 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.

Compatibility

Current target: Claude Code 2.1.216. 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.

Requirements

• Bun 1.4 canary (the Rust rewrite, managed via mise's GitHub backend)
• 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 formatted 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/.

Runtime Tooling Assumptions

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:

MCP Tooling Assumptions

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.

Disclaimer

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.

License

MIT