Claude Code Source Recovery

This repository is a source-recovery and refactoring workspace for @anthropic-ai/claude-code@2.1.81.

The upstream distributable is the bundled CLI in cli.js. The goal here is to move from that bundle-derived codebase toward a maintainable TypeScript project with:

• first-party source in src/claude-code
• third-party packages isolated behind explicit imports
• a generated, loadable JS recovery tree in recovered-js
• direct source-level tests in addition to bundle-regression tests

Current model

There are three important representations in this repo:

1. cli.js The behavioral oracle. This is the original bundled CLI that the project is being recovered from.

2. src/claude-code The transitional first-party source tree. This is where refactoring work happens. New extractions should land here as normal modules with direct imports, not as more bundle-era wrappers.

3. recovered-js A generated JS tree emitted from src/claude-code. It exists to keep a clean executable/loadable recovery target while the TS tree is still being normalized.

Key directories

• src/claude-code/core The main recovery target. Most of the large merged files live here, alongside progressively extracted source modules.

• src/claude-code/vendor The source-side third-party boundary. First-party code should import through these wrappers instead of importing npm packages directly.

• recovered-js/_externals Generated JS-side third-party wrappers used by the recovered tree.

• tests Mixed validation:

  • bundle/harness regression tests
  • direct source-level TS tests
  • generated JS/loadability checks

• scripts AST-backed normalization and recovery scripts. Prefer these over regex-based transforms for structural work.

• src/_mirror_map.json Generated crosswalk from this recovery tree to the preferred external reference tree at ../../claude-code-source-reference/src (clone of hangsman/claude-code-source), or CLAUDE_CODE_MIRROR_DIR if overridden. Falls back to ../../anthropic-leaked-source-code only if the preferred reference tree is absent.

• src/_sourcemap_map.json Generated crosswalk from this recovery tree to the preferred source map at ../../claude-code-source-reference/cli.js.map, or CLAUDE_CODE_SOURCEMAP_FILE if overridden. Falls back to ~/Downloads/cli.js.map only if the preferred source map is absent.

Working rules

• Treat cli.js as the behavioral reference until source parity is proven.
• Treat src/claude-code as the place for maintainable code.
• Treat recovered-js as generated output. Do not hand-edit it.
• Prefer extracting semantic seams from large merged files instead of doing blind one-file-per-wrapper splits.
• Keep third-party code out of src/claude-code; route it through src/claude-code/vendor.

Useful commands

Install dependencies:

npm install

Run the full validation path:

npm run ci

Regenerate the generated artifacts after source edits:

npm run sync:generated

Check generated artifacts without rewriting them:

npm run check:generated

Regenerate the optional mirror crosswalk:

npm run map:mirror

Regenerate the source-map crosswalk:

npm run map:sourcemap

Regenerate both preferred reference crosswalks:

npm run map:reference

Check the recovered JS tree is loadable:

npm run recover:js:loadcheck

Check the source CLI path directly:

npm run source:cli:check

Bundle-oriented validation:

npm run build
npm run verify

Source validation:

npm run typecheck
npm test

Recommended workflow

1. Extract a coherent seam from a large merged file in src/claude-code/core.
2. Add direct tests for the new source module.
3. Run npm run typecheck and the relevant focused tests.
4. Run npm run sync:generated.
5. Run npm run ci.

Long-term end state

The target is not "prettier generated output." The target is a normal TS module graph where:

• src is the source of truth
• vendor packages are explicit imports
• tests run against source directly
• the recovered/generated compatibility layers can eventually be deleted