Jayden/claude-code-2026-04-02
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add documentation

Browse Source
This commit is contained in:
Osman Mehmood
2026-03-31 15:38:58 +05:00
parent b7a82da0be
commit 9024f81eb7
32 changed files with 941 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
.github/workflows/pages.yml vendored Normal file
View File

@@ -0,0 +1,44 @@
name: Deploy documentation to GitHub Pages
on:
push:
branches:
- main
paths:
- "docs-site/**"
- ".github/workflows/pages.yml"
- "README.md"
workflow_dispatch:
permissions:
contents: write
concurrency:
group: pages-deploy
cancel-in-progress: true
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
cache-dependency-path: docs-site/requirements.txt
- name: Install MkDocs Material
run: pip install -r docs-site/requirements.txt
- name: Build site
run: mkdocs build -f docs-site/mkdocs.yml
- name: Deploy to gh-pages branch
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs-site/site
force_orphan: true
enable_jekyll: false

4
.gitignore vendored
View File

@@ -1 +1,3 @@
.DS_Store
.DS_Store
docs-site/.venv/
docs-site/site/

26
README.md
View File

@@ -119,8 +119,32 @@ src/
Execution paths converge on shared **state** (`state/`, `bootstrap/`), **permissions** (`utils/permissions/`), and **session storage** (`utils/sessionStorage.js`, hooks in `utils/sessionStart.js`). Non-interactive and SDK-style use share much of the same stack as the full-screen REPL, with different front-ends for I/O.
## Documentation (GitHub Pages)
Full internals documentation (architecture, workflows, official-docs cross-reference, subsystem reference, appendices) is built with **MkDocs Material** from [`docs-site/`](docs-site/).
- **Live site:** after you enable GitHub Pages on the `gh-pages` branch, the site is served at
`https://<your-github-user>.github.io/claude-code-source-code/`
(replace with your fork’s user/org and repo name).
- **Local preview:** `cd docs-site && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && mkdocs serve`
- **Publish:** pushing to `main` runs [`.github/workflows/pages.yml`](.github/workflows/pages.yml) and deploys to `gh-pages`.
Update `site_url` and `repo_url` in [`docs-site/mkdocs.yml`](docs-site/mkdocs.yml) after the first deploy so canonical URLs match your fork.
**Contributing to docs:** edit Markdown under `docs-site/docs/`; keep the [official docs map](docs-site/docs/official-docs-map.md) in sync with [Anthropic’s docs index](https://code.claude.com/docs/llms.txt) when adding major features.
### Next steps (first-time publish)
1. **Commit and push** this repository to GitHub (`main` must contain `docs-site/` and `.github/workflows/pages.yml`).
2. **Allow the workflow to run** — GitHub Actions → _Deploy documentation to GitHub Pages_ → confirm it completes (or run **Run workflow** manually).
3. **Turn on Pages** — Repository **Settings → Pages** → **Build and deployment** → Source: **Deploy from a branch** → Branch **`gh-pages`** / folder **`/ (root)`**. (If you prefer the newer “GitHub Actions” source, switch the workflow to `actions/upload-pages-artifact` + `deploy-pages` instead of peaceiris.)
4. **Set `site_url`** in [`docs-site/mkdocs.yml`](docs-site/mkdocs.yml) to your live URL (e.g. `https://YOUR_USER.github.io/claude-code-source-code/`) and push again so sitemaps and search use the correct base.
5. **Fork-specific URLs** — Update `repo_url`, `edit_uri`, and the `extra.social` GitHub link in `mkdocs.yml` if this is not `marium/claude-code-source-code`.
## Repository layout
- **`src/`** — Application source (thousands of modules) as recovered from the bundle map.
- **`docs/`** — Human-readable layout reference ([directory-structure.md](docs/directory-structure.md)).
- **`docs-site/`** — MkDocs source for the GitHub Pages documentation site.
- **`docs/`** — Short pointer plus [`directory-structure.md`](docs/directory-structure.md) (`src/` layout reference).
- **`scripts/`** — Optional helpers (e.g. `gen-appendices.sh`).
- There is **no `package.json` in this clone**; building would require the original toolchain (Bun, internal `bun:bundle` features, and private deps). Treat this tree as a **read-only architectural reference**.

3
docs-site/.gitignore vendored Normal file
View File

@@ -0,0 +1,3 @@
.venv/
site/
docs/appendix/_generated-env-vars.txt

78
docs-site/docs/appendix/directory-structure.md Normal file
View File

@@ -0,0 +1,78 @@
# Directory structure (`src/`)
This mirrors the **top levels** of the recovered `src/` tree. The repo also keeps `docs/directory-structure.md` at the repository root for browsing without MkDocs.
## Package root files
| File | Notes |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `main.tsx` | CLI entry: Commander setup, `preAction` trust/settings/telemetry, routing to REPL or print mode |
| `commands.ts` | Command registry |
| `tools.ts` | Tool registry (see also `tools/` directory) |
| `Tool.ts` | Tool types / shared tool definitions |
| `QueryEngine.ts` | Model / API query pipeline |
| `context.ts` | System and user context |
| `cost-tracker.ts` | Token / cost tracking |
| `costHook.ts` | Cost hook wiring |
| `dialogLaunchers.tsx` | Ink dialogs (resume, settings, teleport, etc.) |
| `history.ts` | Input history |
| `ink.ts` | Ink root / render helpers |
| `interactiveHelpers.tsx` | Interactive UI helpers |
| `projectOnboardingState.ts` | Onboarding state |
| `query.ts` | Query helpers |
| `replLauncher.tsx` | REPL launch |
| `setup.ts` | Setup flows |
| `tasks.ts` | Task utilities / constants |
| `Task.ts` | Task types |
## Top-level directories
| Directory | Role |
| ---------------- | ----------------------------------------------------------------------- |
| `assistant/` | Assistant / KAIROS paths (bundle feature-gated) |
| `bootstrap/` | Early boot and global flags (cwd, remote mode, overrides) |
| `bridge/` | IDE integration (VS Code, JetBrains, etc.) |
| `buddy/` | Companion / buddy UI |
| `cli/` | Non-interactive / print mode, transports, NDJSON, subcommand handlers |
| `commands/` | Slash commands and related CLI command modules |
| `components/` | Ink/React UI components |
| `constants/` | Shared constants (OAuth, product URLs, etc.) |
| `context/` | Context subsystems (stats, attachments, etc.) |
| `coordinator/` | Multi-agent coordinator (feature-gated) |
| `entrypoints/` | `init` and related startup entrypoints |
| `hooks/` | React hooks for the terminal UI |
| `ink/` | Ink layout, termio, events (terminal renderer layer) |
| `keybindings/` | Keybinding definitions and providers |
| `memdir/` | Memory directory / persistent memory |
| `migrations/` | Settings and data migrations |
| `moreright/` | Internal layout / UI helper |
| `native-ts/` | Native TypeScript helpers |
| `outputStyles/` | Output styling |
| `plugins/` | Plugin loader and bundled plugins |
| `query/` | Query pipeline modules |
| `remote/` | Remote session / control |
| `schemas/` | Zod (and related) schemas |
| `screens/` | Full-screen flows (doctor, REPL shell, resume) |
| `server/` | Server / socket modes |
| `services/` | API client, MCP, compaction, LSP, analytics, OAuth, policy, etc. |
| `skills/` | Skill loading and bundled skills |
| `state/` | App state providers and reducers |
| `tasks/` | Task implementations (local agent, shell, remote, dream, etc.) |
| `tools/` | One subdirectory per agent-invokable tool |
| `types/` | Shared TypeScript types (incl. generated) |
| `upstreamproxy/` | Upstream proxy configuration |
| `utils/` | Large catch-all: permissions, settings, swarm, shell, git, telemetry, … |
| `vim/` | Vim-style editing in the terminal |
| `voice/` | Voice input |
## `services/` (second level)
Includes among others: `api/`, `mcp/`, `compact/`, `lsp/`, `oauth/`, `analytics/`, `policyLimits/`, `remoteManagedSettings/`, `plugins/`, `tools/` (service-side tool orchestration), `teamMemorySync/`, `settingsSync/`, `tips/`, `SessionMemory/`, `autoDream/`, `extractMemories/`, plus standalone `.ts` / `.tsx` files for limits, voice, notifier, etc.
## `tools/` (agent tools)
Each major capability is typically its own folder; see [Tool packages](tool-packages.md) for a full directory list.
## `utils/` (highlights)
Not exhaustive: `swarm/` (teammates, tmux/iTerm backends), `settings/` (incl. `mdm/`), `permissions/`, `shell/`, `telemetry/`, `teleport/`, `deepLink/`, `claudeInChrome/`, `computerUse/`, `messages/`, `sessionStorage.ts`, `sessionStart.ts`, `git.ts`, `config.ts`, `auth.ts`, and hundreds of focused modules.

41
docs-site/docs/appendix/environment-variables.md Normal file
View File

@@ -0,0 +1,41 @@
# Environment variables (code references)
!!! warning "Unofficial and incomplete"
This list is **not** a substitute for the official [Environment variables](https://code.claude.com/docs/en/env-vars) reference. It only shows names that appear in the recovered `src/` tree as `process.env.*` (or standard vars like `HOME`). Behavior and stability are defined by Anthropic’s product, not this mirror.
## User-facing and integration (examples found in source)
| Variable | Where used (indicative) |
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL` | API client / proxy routing (`toolSearch.ts`, auth paths) |
| `CLAUDE_CODE_GIT_BASH_PATH` | Windows Git Bash resolution (`windowsPaths.ts`) |
| `CLAUDE_DEBUG` | Debug logging (`warningHandler.ts`) |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | OpenTelemetry enable (`telemetry/instrumentation.ts`) |
| `CLAUDE_CODE_ENABLE_TASKS` | Tasks mode (`tasks.ts`) |
| `CLAUDE_CODE_TASK_LIST_ID` | Default task list id (`tasks.ts`) |
| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | Plan mode gate (`teammate.ts`) |
| `CLAUDE_CODE_WORKSPACE_HOST_PATHS` | Telemetry workspace mapping (`telemetry/events.ts`) |
| `ENABLE_TOOL_SEARCH` | Tool search beta (`toolSearch.ts`) |
| `GITHUB_ACTIONS` / `GITHUB_*` | CI metadata in analytics (`user.ts`) |
| `HOME` | XDG / paths (`xdg.ts`) |
| `MAX_THINKING_TOKENS` | Thinking toggle (`thinking.ts`) |
| `NODE_ENV` | Dev/test branches |
| `OTEL_*` | OpenTelemetry exporters and endpoints (`telemetry/instrumentation.ts`, `sessionTracing.ts`) |
| `SHELL` | Shell spawning (`terminalPanel.ts`, `windowsPaths.ts`) |
| `TMUX` / `TMUX_PANE` | Worktree / swarm backends (`worktree.ts`, `swarm/backends/detection.ts`) |
| `TMPDIR` | Temp paths (`tmuxSocket.ts`) |
| `USER_TYPE` | Internal Anthropic gating (`undercover.ts`, many modules) |
## Internal / experimental (often `USER_TYPE === 'ant'`)
Variables such as `CLAUDE_CODE_UNDERCOVER`, `ANT_OTEL_*`, `ANT_CLAUDE_CODE_METRICS_ENDPOINT`, `BETA_TRACING_ENDPOINT`, `CCR_FORCE_BUNDLE`, `CCR_ENABLE_BUNDLE`, and similar appear for **employee or beta** builds. Treat them as undocumented implementation details.
## Regenerate a full grep index
From the repo root:
```bash
rg -o 'process\.env\.[A-Za-z0-9_]+' src --glob '*.ts' --glob '*.tsx' | sort -u
```
The script `scripts/gen-appendices.sh` can write the output to `docs-site/docs/appendix/_generated-env-vars.txt` (gitignored) for local analysis.

50
docs-site/docs/appendix/tool-packages.md Normal file
View File

@@ -0,0 +1,50 @@
# Tool packages under `src/tools/`
Each row is a package directory implementing or supporting an agent tool. Names align with the public [Tools reference](https://code.claude.com/docs/en/tools-reference) where applicable.
| Package | Path |
| ---------------------- | --------------------------------- |
| `AgentTool` | `src/tools/AgentTool/` |
| `AskUserQuestionTool` | `src/tools/AskUserQuestionTool/` |
| `BashTool` | `src/tools/BashTool/` |
| `BriefTool` | `src/tools/BriefTool/` |
| `ConfigTool` | `src/tools/ConfigTool/` |
| `EnterPlanModeTool` | `src/tools/EnterPlanModeTool/` |
| `EnterWorktreeTool` | `src/tools/EnterWorktreeTool/` |
| `ExitPlanModeTool` | `src/tools/ExitPlanModeTool/` |
| `ExitWorktreeTool` | `src/tools/ExitWorktreeTool/` |
| `FileEditTool` | `src/tools/FileEditTool/` |
| `FileReadTool` | `src/tools/FileReadTool/` |
| `FileWriteTool` | `src/tools/FileWriteTool/` |
| `GlobTool` | `src/tools/GlobTool/` |
| `GrepTool` | `src/tools/GrepTool/` |
| `LSPTool` | `src/tools/LSPTool/` |
| `ListMcpResourcesTool` | `src/tools/ListMcpResourcesTool/` |
| `MCPTool` | `src/tools/MCPTool/` |
| `McpAuthTool` | `src/tools/McpAuthTool/` |
| `NotebookEditTool` | `src/tools/NotebookEditTool/` |
| `PowerShellTool` | `src/tools/PowerShellTool/` |
| `REPLTool` | `src/tools/REPLTool/` |
| `ReadMcpResourceTool` | `src/tools/ReadMcpResourceTool/` |
| `RemoteTriggerTool` | `src/tools/RemoteTriggerTool/` |
| `ScheduleCronTool` | `src/tools/ScheduleCronTool/` |
| `SendMessageTool` | `src/tools/SendMessageTool/` |
| `SkillTool` | `src/tools/SkillTool/` |
| `SleepTool` | `src/tools/SleepTool/` |
| `SyntheticOutputTool` | `src/tools/SyntheticOutputTool/` |
| `TaskCreateTool` | `src/tools/TaskCreateTool/` |
| `TaskGetTool` | `src/tools/TaskGetTool/` |
| `TaskListTool` | `src/tools/TaskListTool/` |
| `TaskOutputTool` | `src/tools/TaskOutputTool/` |
| `TaskStopTool` | `src/tools/TaskStopTool/` |
| `TaskUpdateTool` | `src/tools/TaskUpdateTool/` |
| `TeamCreateTool` | `src/tools/TeamCreateTool/` |
| `TeamDeleteTool` | `src/tools/TeamDeleteTool/` |
| `TodoWriteTool` | `src/tools/TodoWriteTool/` |
| `ToolSearchTool` | `src/tools/ToolSearchTool/` |
| `WebFetchTool` | `src/tools/WebFetchTool/` |
| `WebSearchTool` | `src/tools/WebSearchTool/` |
| `shared` | `src/tools/shared/` |
| `testing` | `src/tools/testing/` |
To regenerate this table, run `scripts/gen-appendices.sh` from the repository root.

93
docs-site/docs/architecture.md Normal file
View File

@@ -0,0 +1,93 @@
# Architecture
!!! warning "Recovered source"
Paths refer to `src/` in this repository. Line-level accuracy is best-effort from the source map reconstruction.
## High-level flow
```mermaid
flowchart LR
subgraph entry [Entry]
mainTsx[main.tsx]
end
subgraph modes [Modes]
repl[REPL.tsx]
print[cli/print.ts]
assistant[assistant KAIROS gate]
end
subgraph core [Core loop]
queryLoop[query.ts queryLoop]
qe[QueryEngine.ts]
toolsReg[tools.ts getTools]
end
subgraph services [Services]
api[services/api]
mcp[services/mcp]
compact[services/compact]
end
mainTsx --> repl
mainTsx --> print
mainTsx -.-> assistant
repl --> queryLoop
print --> qe
queryLoop --> api
qe --> api
toolsReg --> mcp
queryLoop --> compact
qe --> compact
```
## Entry and startup
`src/main.tsx` is the **Commander**-based CLI. Before the command handler runs, module evaluation triggers:
- Startup profiling checkpoints (`utils/startupProfiler.ts`)
- MDM raw reads in parallel (`utils/settings/mdm/rawRead.ts`)
- macOS keychain prefetch (`utils/secureStorage/keychainPrefetch.ts`)
The `preAction` hook loads trust, settings, telemetry gates, MCP prefetch, policy limits, and related startup work before interactive or print mode begins.
## Interactive mode
- `replLauncher.tsx` mounts the Ink/React app.
- `screens/REPL.tsx` owns the main session UI, input queue, model turns, tool execution UI, teammate hooks, voice (when compiled in), and scheduled-task integration.
- `utils/queueProcessor.ts` drains slash commands, bash-mode lines, and batched prompts into `executeInput`.
## Headless / print / SDK-style I/O
- `cli/print.ts` implements structured stdin/stdout loops (`runHeadlessStreaming`, NDJSON-style control).
- `QueryEngine.ts` supports non-REPL paths where messages are submitted programmatically and tool permission context is updated without full UI.
## Tools and MCP
- `tools.ts` aggregates built-in tools (filtered by permission context) and merges MCP-derived tools.
- `services/mcp/` implements config parsing, transports, OAuth, channel permissions, and the in-process MCP client used by `MCPConnectionManager` in the UI.
## Compaction and memory
- `services/compact/` implements context window management aligned with user-facing [context window](https://code.claude.com/docs/en/context-window) and [costs](https://code.claude.com/docs/en/costs) documentation.
## Multi-agent (swarm / teammates)
- `utils/swarm/` contains backends (tmux, iTerm, in-process), spawn utilities, permission sync, and `inProcessRunner.ts` teammate loop.
## IDE integration
- `bridge/` plus hooks such as `hooks/useDiffInIDE.ts` connect to VS Code / JetBrains surfaces described in official [VS Code](https://code.claude.com/docs/en/vs-code) and [JetBrains](https://code.claude.com/docs/en/jetbrains) docs.
## Key files (quick index)
| Path | Role |
| -------------------------------------------------- | ------------------------------------------- |
| `main.tsx` | CLI entry, global options, `preAction` |
| `screens/REPL.tsx` | Interactive session core |
| `query.ts` | Streaming query loop, tool round-trips |
| `QueryEngine.ts` | Headless query submission |
| `cli/print.ts` | Print / stream-json / SDK control transport |
| `tools.ts` / `Tool.ts` | Tool registry and types |
| `services/api/client.ts`, `services/api/claude.ts` | HTTP / streaming API |
| `utils/permissions/` | Permission modes and prompts |
| `services/compact/` | Compaction pipeline |
| `utils/sessionStart.ts` | Session / setup hooks |
See also [Workflows](workflows.md) and the [official docs map](official-docs-map.md).

30
docs-site/docs/index.md Normal file
View File

@@ -0,0 +1,30 @@
# Claude Code — recovered source internals
!!! warning "Proprietary software / leaked reconstruction"
This repository contains **reconstructed TypeScript source** from a published npm bundle source map (March 2026). The software is **Anthropic’s proprietary product**. These docs are for **education and architecture study** only. Building or redistributing a competing product may violate law or Anthropic’s terms. This site is **not** official documentation and **not** Anthropic support.
This documentation maps the **`src/`** tree of the Claude Code CLI to **how the product behaves**, with cross-links to **[official Claude Code documentation](https://code.claude.com/docs/en/overview)**.
## What Claude Code is (official product)
From the [product overview](https://code.claude.com/docs/en/overview):
> Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser.
The recovered codebase implements primarily the **terminal CLI** surface, plus shared logic for tools, MCP, permissions, compaction, IDE bridge hooks, and related services.
## How to use this site
| Section | Purpose |
| ------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Installation](installation.md) | Build **this documentation** locally; install the **real** Claude Code from Anthropic. |
| [Reproducibility](reproducibility.md) | Why you **cannot** rebuild the shipping npm package from this tree alone. |
| [Architecture](architecture.md) | High-level components and data flow. |
| [Workflows](workflows.md) | Interactive REPL, print/headless, swarm, compaction paths. |
| [Official docs map](official-docs-map.md) | Every indexed doc page ↔ `src/` entry points. |
| [Reference](reference/cli-entry.md) | Deeper dives per subsystem. |
| [Appendix](appendix/directory-structure.md) | Directory layout, tool packages, environment variables. |
## Repository
Source code lives under `src/` in the GitHub repository. The published MkDocs site is built from `docs-site/` via GitHub Actions. After enabling Pages on the `gh-pages` branch, the URL is typically `https://<user>.github.io/<repo>/` (see the root `README.md`).

36
docs-site/docs/installation.md Normal file
View File

@@ -0,0 +1,36 @@
# Installation
!!! warning "Two different things"
**A)** Building this **documentation site** (MkDocs) — instructions below.
**B)** Installing **Claude Code** the product — use Anthropic’s official installers only.
## Install Claude Code (official product)
Follow the [Claude Code overview](https://code.claude.com/docs/en/overview): native install script, Homebrew, WinGet, VS Code extension, JetBrains plugin, desktop app, or web. This recovered repository **does not** ship a supported way to compile or install the product from source.
## Build this documentation site (local)
Requires Python 3.10+.
```bash
cd docs-site
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
mkdocs serve
```
Open `http://127.0.0.1:8000` to preview.
## Publish (GitHub Pages)
On push to `main`, the workflow `.github/workflows/pages.yml` builds the site and pushes to the `gh-pages` branch (also runs when `README.md` or the workflow file changes).
1. In the GitHub repo: **Settings → Pages → Build and deployment → Branch `gh-pages` / `/ (root)`**.
2. After the first deploy, set `site_url` in `docs-site/mkdocs.yml` to your real Pages URL (e.g. `https://<user>.github.io/<repo>/`) so canonical links and search work correctly. Also update `repo_url` if your fork uses a different owner or name.
The deploy step sets **`enable_jekyll: false`** so GitHub Pages serves static files correctly (adds `.nojekyll`).
## Advanced setup (official)
For system requirements, updates, and uninstallation of the **product**, see [Advanced setup](https://code.claude.com/docs/en/setup) in the official docs.

154
docs-site/docs/official-docs-map.md Normal file
View File

@@ -0,0 +1,154 @@
# Official Claude Code docs ↔ `src/` map
This table links each page listed in the [official docs index (`llms.txt`)](https://code.claude.com/docs/llms.txt) to **primary** paths under `src/`. Many features span multiple folders; only entry points and main implementations are shown. Rows marked _user guide_ have no single code anchor.
!!! tip "Canonical user documentation"
For behavior, flags, and configuration, always prefer **[code.claude.com/docs](https://code.claude.com/docs/en/overview)**. This map is for **code navigation** in the recovered tree.
## Product, platforms, and onboarding
| Official doc | Primary `src/` paths | Notes |
| ------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------- |
| [Overview](https://code.claude.com/docs/en/overview.md) | `main.tsx`, `screens/REPL.tsx` | Product surfaces; CLI is one implementation |
| [Quickstart](https://code.claude.com/docs/en/quickstart.md) | _user guide_ | |
| [Platforms and integrations](https://code.claude.com/docs/en/platforms.md) | `bridge/`, `cli/`, `remote/` | |
| [Common workflows](https://code.claude.com/docs/en/common-workflows.md) | _user guide_ | |
| [Best practices](https://code.claude.com/docs/en/best-practices.md) | _user guide_ | |
| [Changelog](https://code.claude.com/docs/en/changelog.md) | _release notes_ | |
| [Troubleshooting](https://code.claude.com/docs/en/troubleshooting.md) | _user guide_ | |
| [Legal and compliance](https://code.claude.com/docs/en/legal-and-compliance.md) | _policy_ | |
| [Data usage](https://code.claude.com/docs/en/data-usage.md) | _policy_ | |
| [Security](https://code.claude.com/docs/en/security.md) | `utils/permissions/`, `utils/shell/` | Safeguards; not exhaustive |
| [Zero data retention](https://code.claude.com/docs/en/zero-data-retention.md) | `services/policyLimits/`, `utils/settings/` | Enterprise policy hooks |
## CLI, terminal, and interaction
| Official doc | Primary `src/` paths | Notes |
| ----------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- |
| [CLI reference](https://code.claude.com/docs/en/cli-reference.md) | `main.tsx`, `commands/` | Flags and subcommands |
| [Interactive mode](https://code.claude.com/docs/en/interactive-mode.md) | `screens/REPL.tsx`, `keybindings/`, `components/` | Shortcuts, input modes (`hooks/` here is React hooks, not user shell hooks) |
| [Terminal config](https://code.claude.com/docs/en/terminal-config.md) | `utils/terminal.ts`, `ink/` | |
| [Keybindings](https://code.claude.com/docs/en/keybindings.md) | `keybindings/` | |
| [Status line](https://code.claude.com/docs/en/statusline.md) | `utils/status.tsx`, `components/` | |
| [Fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md) | `ink/`, `components/` | |
| [Voice dictation](https://code.claude.com/docs/en/voice-dictation.md) | `voice/`, `screens/REPL.tsx` | Gated by `VOICE_MODE` in bundle |
| [Built-in commands](https://code.claude.com/docs/en/commands.md) | `commands/` | Slash commands |
| [Output styles](https://code.claude.com/docs/en/output-styles.md) | `outputStyles/` | |
## Agent loop, tools, and context
| Official doc | Primary `src/` paths | Notes |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------- |
| [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md) | `query.ts`, `tools.ts`, `services/tools/` | Agentic loop |
| [Headless / programmatic](https://code.claude.com/docs/en/headless.md) | `cli/print.ts`, `QueryEngine.ts` | Stream-json / SDK control |
| [Tools reference](https://code.claude.com/docs/en/tools-reference.md) | `tools/*`, `Tool.ts`, `services/lsp/` | Includes LSP tool |
| [Context window](https://code.claude.com/docs/en/context-window.md) | `services/compact/`, `utils/tokenBudget.ts` | |
| [Checkpointing](https://code.claude.com/docs/en/checkpointing.md) | `utils/sessionStorage.ts`, `utils/conversationRecovery.ts` | |
| [Costs](https://code.claude.com/docs/en/costs.md) | `cost-tracker.ts`, `services/api/usage.ts` | Token usage and limits |
| [Sandboxing](https://code.claude.com/docs/en/sandboxing.md) | `utils/shell/`, `tools/BashTool/` | Bash isolation |
| [Computer use](https://code.claude.com/docs/en/computer-use.md) | `utils/computerUse/` | CLI computer-use MCP |
| [Fast mode](https://code.claude.com/docs/en/fast-mode.md) | `utils/fastMode.ts` | |
## MCP, channels, and extensions
| Official doc | Primary `src/` paths | Notes |
| ----------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------- |
| [MCP](https://code.claude.com/docs/en/mcp.md) | `services/mcp/`, `tools/MCPTool/` | |
| [Channels](https://code.claude.com/docs/en/channels.md) | `services/mcp/channel*.ts` | Inbound push |
| [Channels reference](https://code.claude.com/docs/en/channels-reference.md) | `services/mcp/` | Contract / capabilities |
| [Hooks guide](https://code.claude.com/docs/en/hooks-guide.md) | `utils/sessionStart.ts`, hook runners | |
| [Hooks reference](https://code.claude.com/docs/en/hooks.md) | `utils/sessionStart.ts`, `schemas/` | JSON schemas |
| [Plugins](https://code.claude.com/docs/en/plugins.md) | `plugins/`, `utils/plugins/` | |
| [Plugins reference](https://code.claude.com/docs/en/plugins-reference.md) | `plugins/`, `services/plugins/` | |
| [Discover plugins](https://code.claude.com/docs/en/discover-plugins.md) | `services/plugins/pluginCliCommands.ts` | |
| [Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces.md) | `utils/plugins/` | |
| [Skills](https://code.claude.com/docs/en/skills.md) | `skills/`, `utils/skills/`, `tools/SkillTool/` | |
| [Features overview](https://code.claude.com/docs/en/features-overview.md) | _cross-cutting_ | CLAUDE.md, skills, MCP, hooks |
## Memory, project config, and `.claude`
| Official doc | Primary `src/` paths | Notes |
| -------------------------------------------------------------------------------- | -------------------------------- | --------------------- |
| [Memory / CLAUDE.md](https://code.claude.com/docs/en/memory.md) | `utils/claudemd.ts`, `memdir/` | |
| [Explore .claude directory](https://code.claude.com/docs/en/claude-directory.md) | `utils/settings/`, `migrations/` | Settings, hooks paths |
## Permissions and models
| Official doc | Primary `src/` paths | Notes |
| ----------------------------------------------------------------------- | -------------------------------------- | -------------------- |
| [Permissions](https://code.claude.com/docs/en/permissions.md) | `utils/permissions/` | |
| [Permission modes](https://code.claude.com/docs/en/permission-modes.md) | `utils/permissions/permissionSetup.ts` | Auto / plan / etc. |
| [Model configuration](https://code.claude.com/docs/en/model-config.md) | `utils/model/` | Aliases, deprecation |
## Multi-agent and scheduling
| Official doc | Primary `src/` paths | Notes |
| ----------------------------------------------------------------------------- | ------------------------------------ | ------------------------------- |
| [Agent teams](https://code.claude.com/docs/en/agent-teams.md) | `utils/swarm/`, `screens/REPL.tsx` | |
| [Subagents](https://code.claude.com/docs/en/sub-agents.md) | `tools/AgentTool/` | |
| [Scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks.md) | `utils/cron*.ts`, `screens/REPL.tsx` | `/loop`, cron tools |
| [Web scheduled tasks](https://code.claude.com/docs/en/web-scheduled-tasks.md) | `services/api/`, `remote/` | Cloud scheduling (client hooks) |
## IDEs, Chrome, remote, desktop
| Official doc | Primary `src/` paths | Notes |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------- |
| [VS Code](https://code.claude.com/docs/en/vs-code.md) | `bridge/`, `hooks/useDiffInIDE.ts` | |
| [JetBrains](https://code.claude.com/docs/en/jetbrains.md) | `bridge/` | |
| [Chrome](https://code.claude.com/docs/en/chrome.md) | `utils/claudeInChrome/` | Extension / native host |
| [Remote control](https://code.claude.com/docs/en/remote-control.md) | `remote/`, `utils/teleport/`, `services/api/sessionIngress.ts` | |
| [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web.md) | `services/api/`, `bootstrap/` | Cloud session client |
| [Desktop](https://code.claude.com/docs/en/desktop.md) | `utils/deepLink/`, `dialogLaunchers.tsx` | Handoff / deep links |
| [Desktop quickstart](https://code.claude.com/docs/en/desktop-quickstart.md) | _user guide_ | |
## Authentication and cloud providers
| Official doc | Primary `src/` paths | Notes |
| ------------------------------------------------------------------------------ | ----------------------------------------- | ----------------- |
| [Authentication](https://code.claude.com/docs/en/authentication.md) | `utils/auth.ts`, `services/oauth/` | |
| [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md) | `utils/aws.ts`, `utils/auth.ts` | |
| [Google Vertex AI](https://code.claude.com/docs/en/google-vertex-ai.md) | `utils/auth.ts`, `services/api/` | |
| [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md) | `services/api/`, `utils/auth.ts` | |
| [LLM gateway](https://code.claude.com/docs/en/llm-gateway.md) | `upstreamproxy/`, `services/api/` | |
| [Enterprise network config](https://code.claude.com/docs/en/network-config.md) | `utils/caCerts.ts`, `utils/managedEnv.ts` | Proxy / mTLS / CA |
## Settings, policy, and enterprise
| Official doc | Primary `src/` paths | Notes |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------- |
| [Settings](https://code.claude.com/docs/en/settings.md) | `utils/settings/` | |
| [Environment variables](https://code.claude.com/docs/en/env-vars.md) | _grep `process.env`_ — [appendix](appendix/environment-variables.md) | |
| [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) | `services/remoteManagedSettings/` | |
| [Third-party integrations / enterprise](https://code.claude.com/docs/en/third-party-integrations.md) | `bridge/`, `services/mcp/`, `utils/settings/mdm/` | |
| [Development containers](https://code.claude.com/docs/en/devcontainer.md) | _user guide_ | |
| [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server.md) | `utils/github/` | Partial |
## CI/CD, review, and chat integrations
| Official doc | Primary `src/` paths | Notes |
| ------------------------------------------------------------------- | ---------------------------------------------- | ---------------------- |
| [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) | _minimal in CLI_ | CI uses product binary |
| [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md) | _minimal in CLI_ | |
| [Code review](https://code.claude.com/docs/en/code-review.md) | _service-side / GitHub app_ | |
| [Slack](https://code.claude.com/docs/en/slack.md) | `utils/suggestions/slackChannelSuggestions.ts` | Integrations |
## Analytics, monitoring, LSP
| Official doc | Primary `src/` paths | Notes |
| --------------------------------------------------------------------------------- | ----------------------------------------- | ----- |
| [Analytics](https://code.claude.com/docs/en/analytics.md) | `services/analytics/` | |
| [Monitoring / OpenTelemetry](https://code.claude.com/docs/en/monitoring-usage.md) | `utils/telemetry/`, `services/analytics/` | |
## Advanced setup
| Official doc | Primary `src/` paths | Notes |
| ------------------------------------------------------------------------------------ | -------------------- | -------------------------------------------------- |
| [Advanced setup](https://code.claude.com/docs/en/setup.md) | _user guide_ | Install / uninstall product |
| [Vim mode](https://code.claude.com/docs/en/interactive-mode.md) | `vim/` | See interactive mode; vim implementation in `vim/` |
| [Coordinator / internal multi-agent](https://code.claude.com/docs/en/agent-teams.md) | `coordinator/` | Bundle feature `COORDINATOR_MODE` |
| [Assistant mode / Agent SDK daemon](https://code.claude.com/docs/en/headless.md) | `assistant/` | Bundle feature `KAIROS` |
</think>
<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>
Read

9
docs-site/docs/reference/api-client.md Normal file
View File

@@ -0,0 +1,9 @@
# API client and OAuth
**Primary paths:** `src/services/api/`, `src/services/oauth/`, `src/utils/api.ts`, `src/utils/auth.ts`
`services/api/client.ts` and `claude.ts` implement HTTP and streaming calls to Anthropic APIs (including retries, errors, session ingress, files API, usage, bootstrap). Provider-specific paths (Bedrock, Vertex, Foundry) are gated through auth and endpoint configuration in `utils/aws.ts`, `utils/auth.ts`, and related modules.
`services/oauth/` implements the browser-based OAuth flow (auth code listener, token exchange, crypto).
**See also:** [Authentication](https://code.claude.com/docs/en/authentication), [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock), [Google Vertex AI](https://code.claude.com/docs/en/google-vertex-ai).

11
docs-site/docs/reference/cli-entry.md Normal file
View File

@@ -0,0 +1,11 @@
# CLI entry and parsing
**Primary paths:** `src/main.tsx`, `src/cli/*`, `src/commands.ts`
`main.tsx` registers the `claude` Commander program: global options (model, permissions, worktree, teammate flags, MCP, teleport, etc.), subcommands (MCP, plugins, agents, auth utilities), and a `preAction` hook that runs trust checks, settings load, telemetry initialization, prefetch (MCP URLs, referral, fast mode), and policy gates before any handler executes.
Side effects at **module top** intentionally run before other imports: startup profiler, MDM subprocess reads (`utils/settings/mdm/rawRead.ts`), and macOS keychain prefetch to overlap I/O with the rest of module evaluation.
Feature-gated dynamic `require()` loads `coordinator/coordinatorMode.js` when `COORDINATOR_MODE` is true in the Bun bundle, and `assistant/` when `KAIROS` is true.
**See also:** [CLI reference](https://code.claude.com/docs/en/cli-reference), [Architecture](../architecture.md).

9
docs-site/docs/reference/compaction.md Normal file
View File

@@ -0,0 +1,9 @@
# Compaction and session memory
**Primary paths:** `src/services/compact/`, `src/services/SessionMemory/`, `src/utils/tokenBudget.ts`
Compaction reduces transcript size when approaching context limits: `compact.ts`, `autoCompact.ts`, `microCompact.ts`, `sessionMemoryCompact.ts`, grouping, prompts, and post-compact cleanup. Time-based and API microcompact paths support different strategies.
Session memory modules add long-lived summaries and structured memory aligned with product behavior described under [memory](https://code.claude.com/docs/en/memory) and [context window](https://code.claude.com/docs/en/context-window).
**See also:** [Context window](https://code.claude.com/docs/en/context-window), [Costs](https://code.claude.com/docs/en/costs), [Checkpointing](https://code.claude.com/docs/en/checkpointing).

9
docs-site/docs/reference/lsp.md Normal file
View File

@@ -0,0 +1,9 @@
# LSP integration
**Primary paths:** `src/services/lsp/`, `src/tools/LSPTool/`
`LSPServerManager.ts`, `LSPClient.ts`, and related modules manage language server processes and diagnostics. The agent invokes LSP capabilities through `LSPTool`, which bridges model tool calls to LSP requests.
Passive feedback and config live alongside the manager (`passiveFeedback.ts`, `config.ts`).
**See also:** [Tools reference](https://code.claude.com/docs/en/tools-reference) (LSP tool), [Architecture](../architecture.md).

11
docs-site/docs/reference/mcp.md Normal file
View File

@@ -0,0 +1,11 @@
# MCP (Model Context Protocol)
**Primary paths:** `src/services/mcp/`, `src/tools/MCPTool/`, `src/tools/McpAuthTool/`, `src/services/mcp/MCPConnectionManager.tsx`
The MCP subsystem parses config (files, env expansion, enterprise allowlists), establishes **stdio** and **in-process** transports, handles OAuth for MCP servers, normalizes server metadata, and exposes tools and resources to the model.
Channel-related files (`channelAllowlist`, `channelNotification`, `channelPermissions`) implement **push** notifications into a session, matching the [Channels](https://code.claude.com/docs/en/channels) documentation.
The React `MCPConnectionManager` wraps interactive sessions so the REPL can connect/disconnect servers and reflect status in the UI.
**See also:** [MCP](https://code.claude.com/docs/en/mcp), [Channels reference](https://code.claude.com/docs/en/channels-reference).

9
docs-site/docs/reference/permissions.md Normal file
View File

@@ -0,0 +1,9 @@
# Permissions and modes
**Primary paths:** `src/utils/permissions/`, `src/utils/permissions/permissionSetup.ts`, `src/utils/permissions/PermissionMode.ts`
Permission modes (manual, auto with classifiers, plan-only, etc.) are parsed from CLI flags and settings, then stored in `toolPermissionContext` on app state. Tool execution consults this context before running bash, file writes, MCP calls, etc.
`permissionSetup.ts` and related modules implement gates for auto mode, dangerous permission stripping, and advisor integration.
**See also:** [Permissions](https://code.claude.com/docs/en/permissions), [Permission modes](https://code.claude.com/docs/en/permission-modes), [Sandboxing](https://code.claude.com/docs/en/sandboxing).

9
docs-site/docs/reference/plugins-skills.md Normal file
View File

@@ -0,0 +1,9 @@
# Plugins and skills
**Primary paths:** `src/plugins/`, `src/skills/`, `src/utils/plugins/`, `src/utils/skills/`, `src/tools/SkillTool/`, `src/services/plugins/`
Bundled plugins ship under `plugins/bundled/`; `PluginInstallationManager` and CLI commands under `services/plugins/` support install/update scopes. Skills load from project and user directories; `skillChangeDetector` watches for changes.
`SkillTool` exposes skill invocation to the model. Hooks and commands defined by plugins align with [Plugins](https://code.claude.com/docs/en/plugins) and [Skills](https://code.claude.com/docs/en/skills).
**See also:** [Plugins reference](https://code.claude.com/docs/en/plugins-reference), [Discover plugins](https://code.claude.com/docs/en/discover-plugins).

11
docs-site/docs/reference/print-sdk.md Normal file
View File

@@ -0,0 +1,11 @@
# Print mode, stream-json, and SDK control
**Primary paths:** `src/cli/print.ts`, `src/cli/structuredIO.ts`, `src/cli/transports/*`, `src/QueryEngine.ts`
`print.ts` implements non-interactive execution: structured stdin lines, streaming stdout (including partial messages), tool permission prompts bridged over the protocol, and verbose/debug modes.
`structuredIO.ts` parses and validates incoming events; transports (`WebSocketTransport`, `SSETransport`, `HybridTransport`, etc.) support remote SDK and CCR-style integrations.
This corresponds to [Headless](https://code.claude.com/docs/en/headless) and Agent SDK usage documented on the Anthropic platform.
**See also:** [Workflows](../workflows.md), [Query loop](query-engine.md).

11
docs-site/docs/reference/query-engine.md Normal file
View File

@@ -0,0 +1,11 @@
# Query loop and streaming
**Primary paths:** `src/query.ts`, `src/QueryEngine.ts`, `src/utils/processUserInput/`
`query.ts` defines `queryLoop`, the async generator that drives a single conversation turn: streams assistant content, handles tool calls, merges tool results back into context, and coordinates with compaction and permission checks.
`QueryEngine.ts` exposes `submitMessage` for **non-interactive** flows: it prepares `processUserInputContext` with `isNonInteractiveSession: true`, runs skill/plugin caches, and streams SDK-style messages—used from headless and SDK control transports.
Shared input processing (slash commands embedded in prompts, tool permission context updates) lives under `utils/processUserInput/` and related modules.
**See also:** [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works), [Headless](https://code.claude.com/docs/en/headless).

13
docs-site/docs/reference/remote-bridge.md Normal file
View File

@@ -0,0 +1,13 @@
# Remote sessions, teleport, IDE bridge, Chrome
**Primary paths:** `src/remote/`, `src/utils/teleport/`, `src/utils/deepLink/`, `src/bridge/`, `src/utils/claudeInChrome/`, `src/hooks/useDiffInIDE.ts`
**Remote / teleport:** `teleport/` handles session bundles, environment selection, and API calls to resume or hand off sessions—aligned with [Remote control](https://code.claude.com/docs/en/remote-control) and web/desktop flows.
**Deep links:** `deepLink/protocolHandler.ts` parses `claude-cli://` URIs and launches the binary in a terminal with the right cwd/repo context.
**IDE bridge:** `bridge/` communicates with VS Code and JetBrains extensions (diffs, context). Hooks like `useDiffInIDE.ts` open IDE-native diff UIs when available.
**Chrome:** `claudeInChrome/` implements native messaging and MCP servers for the [Chrome](https://code.claude.com/docs/en/chrome) beta workflow.
**See also:** [VS Code](https://code.claude.com/docs/en/vs-code), [JetBrains](https://code.claude.com/docs/en/jetbrains), [Desktop](https://code.claude.com/docs/en/desktop).

11
docs-site/docs/reference/repl-ui.md Normal file
View File

@@ -0,0 +1,11 @@
# REPL and terminal UI
**Primary paths:** `src/screens/REPL.tsx`, `src/components/`, `src/ink/`, `src/replLauncher.tsx`, `src/interactiveHelpers.tsx`
The interactive session is a **React + Ink** application. `replLauncher.tsx` mounts the Ink root and wraps the tree with providers for app state, keybindings, MCP connections, and plugin context.
`REPL.tsx` is large and central: it manages the transcript, loading state, `onQuery` invocations, tool use UI, permission prompts, teammate inbox polling, mailbox bridge, voice integration when `VOICE_MODE` is compiled in, scheduled cron integration, and queue processing between turns.
`ink/` contains layout primitives, terminal I/O helpers, and event wiring specific to the TUI. `components/` holds feature UI (modals, tool output, plan mode, etc.).
**See also:** [Interactive mode](https://code.claude.com/docs/en/interactive-mode), [Fullscreen](https://code.claude.com/docs/en/fullscreen), [Workflows](../workflows.md).

11
docs-site/docs/reference/settings-policy.md Normal file
View File

@@ -0,0 +1,11 @@
# Settings, policy, and remote management
**Primary paths:** `src/utils/settings/`, `src/services/policyLimits/`, `src/services/remoteManagedSettings/`, `src/schemas/`, `src/migrations/`
`settings.ts` and `settingsCache.ts` load merged global and project settings. `mdm/` contains macOS managed-device reads. `validation.ts` enforces schema and tool allowlists.
`policyLimits/` loads enterprise caps (models, spend, features). `remoteManagedSettings/` syncs server-delivered configuration described in [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings).
`migrations/` upgrades on-disk settings between versions.
**See also:** [Settings](https://code.claude.com/docs/en/settings), [Environment variables](https://code.claude.com/docs/en/env-vars).

7
docs-site/docs/reference/telemetry.md Normal file
View File

@@ -0,0 +1,7 @@
# Analytics and telemetry
**Primary paths:** `src/services/analytics/`, `src/utils/telemetry/`
Event logging, GrowthBook/feature flags, Datadog and first-party exporters, session tracing (including Perfetto-oriented paths), and plugin/skill load telemetry live here. Analytics respects disable flags and trust gating initialized after user consent.
**See also:** [Analytics](https://code.claude.com/docs/en/analytics), [Monitoring](https://code.claude.com/docs/en/monitoring-usage).

11
docs-site/docs/reference/tools.md Normal file
View File

@@ -0,0 +1,11 @@
# Tools registry and execution
**Primary paths:** `src/tools.ts`, `src/Tool.ts`, `src/tools/*`, `src/services/tools/`
`tools.ts` exposes `getTools(permissionContext)` and helpers to merge **built-in** tools with **MCP-derived** tools. Built-ins live as one package per directory under `tools/` (e.g. `BashTool`, `FileReadTool`, `GlobTool`, `WebSearchTool`, `AgentTool`).
`services/tools/` contains orchestration: `toolExecution.ts`, `StreamingToolExecutor.ts`, `toolHooks.ts`, hooking tool lifecycle into analytics and permission systems.
Tool schemas and permission requirements align with the public [Tools reference](https://code.claude.com/docs/en/tools-reference); this tree is the implementation of those capabilities.
**See also:** [Tools reference](https://code.claude.com/docs/en/tools-reference), [Appendix: tool packages](../appendix/tool-packages.md).

11
docs-site/docs/reference/voice-vim-output.md Normal file
View File

@@ -0,0 +1,11 @@
# Voice, Vim, and output styles
**Primary paths:** `src/voice/`, `src/vim/`, `src/outputStyles/`, `src/screens/REPL.tsx` (voice hook)
Voice dictation integrates through `useVoiceIntegration` in `REPL.tsx` when the bundle includes `VOICE_MODE`. `voice/` contains mode and streaming helpers.
`vim/` implements modal editing for the prompt (motions, operators, text objects) consistent with [Interactive mode](https://code.claude.com/docs/en/interactive-mode) keyboard behavior.
`outputStyles/` adapts presentation for non-default “output styles” described in the [Output styles](https://code.claude.com/docs/en/output-styles) doc.
**See also:** [Voice dictation](https://code.claude.com/docs/en/voice-dictation), [Keybindings](https://code.claude.com/docs/en/keybindings).

32
docs-site/docs/reproducibility.md Normal file
View File

@@ -0,0 +1,32 @@
# Reproducibility and limits
!!! warning "You cannot rebuild the shipping CLI from this tree alone"
This folder is a **source reconstruction**, not a complete open-source project drop.
## What is missing for a full build
1. **No root `package.json`**
The published npm package bundles dependencies internally. This repo does not declare versions or scripts to reproduce that bundle.
2. **Bun-specific build features**
The entry module uses `bun:bundle` APIs such as `feature('KAIROS')`, `feature('COORDINATOR_MODE')`, `feature('VOICE_MODE')`, etc. Those are compile-time gates in Anthropic’s **internal** bundling pipeline, not something you can flip in a stock TypeScript compile.
3. **Private or unpublished packages**
Imports may reference packages or paths that exist only inside Anthropic’s build graph.
4. **Native addons**
Some flows (keychain, protocol handlers, optional NAPI modules) assume native binaries shipped beside the real `claude` executable.
## What you _can_ do with this tree
- **Read and trace** control flow: `main.tsx` → REPL or `cli/print.ts` → `query.ts` / `QueryEngine.ts` → `services/api` → tools.
- **Compare behavior** to the public [CLI reference](https://code.claude.com/docs/en/cli-reference) and [how Claude Code works](https://code.claude.com/docs/en/how-claude-code-works).
- **Study** MCP, permissions, compaction, hooks, and IDE bridge code against [official feature docs](https://code.claude.com/docs/en/features-overview).
## “Infrastructure” in the sense of this codebase
There is **no** separate microservice repo here: the CLI is a **single process** (plus child processes for bash, MCP servers, etc.) that talks to **Anthropic’s cloud APIs** and optional **MCP** servers over stdio/WebSocket. Enterprise features (remote-managed settings, policy limits, OAuth) are implemented as **client-side** modules under `src/services/` and `src/utils/settings/`, not as deployable server code in this tree.
## Legal
Rebuilding or redistributing the product for end users is outside the scope of these docs and may infringe Anthropic’s rights. Use this material for **analysis** only unless you have explicit permission.

77
docs-site/docs/workflows.md Normal file
View File

@@ -0,0 +1,77 @@
# End-to-end workflows
!!! warning "Recovered source"
Behavior described here is inferred from `src/`; the shipping product may differ by version or build flags.
## Interactive terminal session
1. **Process start** — `main.tsx` evaluates side-effect imports (profiler, MDM, keychain prefetch), then parses argv with Commander.
2. **`preAction` hook** — Trust dialog state, global config, remote-managed settings, policy limits, GrowthBook/feature flags, OAuth/API key paths, MCP official registry prefetch, plugin initialization, and similar steps run before the subcommand handler.
3. **REPL launch** — `replLauncher.tsx` creates the Ink root and renders providers (`AppState`, keybindings, MCP manager, etc.) and mounts `screens/REPL.tsx`.
4. **Input** — User typing, paste, voice (if `VOICE_MODE`), teammate messages, and task notifications enqueue work.
5. **Queue** — `utils/queueProcessor.ts` dequeues slash commands and bash lines individually; batches other same-mode items and calls `executeInput`.
6. **Query** — `query.ts` `queryLoop` streams model output, schedules tool calls, applies permission checks, and updates transcript state.
7. **Tools** — `services/tools/toolExecution.ts` / `StreamingToolExecutor` and per-tool modules under `tools/*` perform filesystem, shell, web, MCP, and agent operations.
8. **Compaction** — When context limits approach, `services/compact/*` reduces history per compaction policy.
**Official parallels:** [Interactive mode](https://code.claude.com/docs/en/interactive-mode), [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works).
## Print mode / stream-json / programmatic control
1. **Routing** — `main.tsx` selects the print/headless path instead of the full REPL when `-p` / related flags are used.
2. **Structured I/O** — `cli/structuredIO.ts` parses lines into typed events; `cli/print.ts` `runHeadlessStreaming` runs the async loop that consumes user/control messages and emits stdout messages.
3. **Engine** — `QueryEngine.submitMessage` builds `processUserInputContext` for non-interactive sessions and streams SDK-style messages.
**Official parallels:** [Run Claude Code programmatically](https://code.claude.com/docs/en/headless), [Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview) (external platform docs).
## Teammates / agent teams
1. **Spawn** — Swarm backends (`utils/swarm/backends/*`) create tmux panes, iTerm panes, or in-process runners.
2. **Teammate loop** — `utils/swarm/inProcessRunner.ts` runs a `while` loop: build prompt messages, check compaction/token limits, call into shared query/tool paths, sync permissions via `leaderPermissionBridge`, etc.
3. **REPL integration** — `REPL.tsx` wires `useInboxPoller`, `useMailboxBridge`, and `handleIncomingPrompt` so teammate messages become user turns.
**Official parallels:** [Agent teams](https://code.claude.com/docs/en/agent-teams), [Subagents](https://code.claude.com/docs/en/sub-agents).
## Hooks (user-configured)
1. **Session start** — `utils/sessionStart.ts` `processSessionStartHooks` / `processSetupHooks` run after configuration is known; wired from startup paths in `main.tsx` and related modules.
2. **Per-event hooks** — Additional hook types align with the schema described in the official [Hooks reference](https://code.claude.com/docs/en/hooks); implementation is spread across hook runners and tool lifecycle code.
**Official parallels:** [Hooks guide](https://code.claude.com/docs/en/hooks-guide), [Hooks reference](https://code.claude.com/docs/en/hooks).
## Compaction and context
1. **Triggers** — Token estimation and session memory modules decide when to compact.
2. **Pipeline** — `services/compact/compact.ts`, `autoCompact.ts`, `microCompact.ts`, and related files rewrite or summarize message history.
3. **Post-compact** — Cleanup hooks update UI and storage.
**Official parallels:** [Context window](https://code.claude.com/docs/en/context-window), [Checkpointing](https://code.claude.com/docs/en/checkpointing), [Costs](https://code.claude.com/docs/en/costs).
## MCP and external tools
1. **Config** — `services/mcp/config.ts`, env expansion, enterprise allowlists.
2. **Connection** — `MCPConnectionManager.tsx`, stdio and SDK transports.
3. **Tool surface** — `tools/MCPTool`, `ReadMcpResourceTool`, `ListMcpResourcesTool`, `McpAuthTool`.
**Official parallels:** [MCP](https://code.claude.com/docs/en/mcp), [Channels](https://code.claude.com/docs/en/channels).
## Optional sequence (interactive turn)
```mermaid
sequenceDiagram
participant User
participant REPL as REPL.tsx
participant Queue as queueProcessor
participant Query as queryLoop
participant API as services/api
participant Tool as tools/*
User->>REPL: input / slash command
REPL->>Queue: enqueue
Queue->>REPL: executeInput
REPL->>Query: onQuery messages
Query->>API: stream completion
API-->>Query: tool_use
Query->>Tool: execute
Tool-->>Query: result
Query-->>REPL: update transcript
```

87
docs-site/mkdocs.yml Normal file
View File

@@ -0,0 +1,87 @@
# Set site_url after first GitHub Pages deploy, e.g. https://YOUR_USER.github.io/claude-code-source-code/
site_name: Claude Code internals (recovered source)
site_description: Architecture and code reference for the reconstructed Claude Code CLI tree, cross-linked to official Anthropic docs.
site_author: Repository maintainers
# Update for your fork:
repo_url: https://github.com/marium/claude-code-source-code
repo_name: claude-code-source-code
edit_uri: edit/main/docs-site/docs/
theme:
name: material
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.top
- search.suggest
- search.highlight
- content.code.copy
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- tables
- toc:
permalink: true
nav:
- Home: index.md
- Getting started:
- installation.md
- reproducibility.md
- Architecture:
- architecture.md
- workflows.md
- Official docs map: official-docs-map.md
- Reference:
- reference/cli-entry.md
- reference/repl-ui.md
- reference/query-engine.md
- reference/tools.md
- reference/mcp.md
- reference/lsp.md
- reference/permissions.md
- reference/compaction.md
- reference/settings-policy.md
- reference/plugins-skills.md
- reference/print-sdk.md
- reference/api-client.md
- reference/telemetry.md
- reference/voice-vim-output.md
- reference/remote-bridge.md
- Appendix:
- appendix/directory-structure.md
- appendix/tool-packages.md
- appendix/environment-variables.md
plugins:
- search
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/marium/claude-code-source-code

1
docs-site/requirements.txt Normal file
View File

@@ -0,0 +1 @@
mkdocs-material>=9.5.0,<10

8
docs/README.md Normal file
View File

@@ -0,0 +1,8 @@
# Documentation
The **MkDocs site** (for GitHub Pages) lives in **`docs-site/`**.
- Source pages: `docs-site/docs/`
- Local preview: `cd docs-site && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && mkdocs serve`
The file **`directory-structure.md`** in this folder remains a quick `src/` layout reference duplicated in the site under **Appendix → Directory structure**.

26
scripts/gen-appendices.sh Executable file
View File

@@ -0,0 +1,26 @@
#!/usr/bin/env bash
# Regenerate appendix artifacts for local analysis (optional).
# Run from repository root: bash scripts/gen-appendices.sh
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
OUT_DIR="$ROOT/docs-site/docs/appendix"
mkdir -p "$OUT_DIR"
echo "# Generated: unique process.env references (do not edit by hand)" > "$OUT_DIR/_generated-env-vars.txt"
echo "" >> "$OUT_DIR/_generated-env-vars.txt"
if command -v rg >/dev/null 2>&1; then
rg -o 'process\.env\.[A-Za-z0-9_]+' "$ROOT/src" --glob '*.ts' --glob '*.tsx' 2>/dev/null | sort -u >> "$OUT_DIR/_generated-env-vars.txt" || true
else
echo "ripgrep (rg) not found; skipped env extraction." >> "$OUT_DIR/_generated-env-vars.txt"
fi
echo "Wrote $OUT_DIR/_generated-env-vars.txt (add to .gitignore if you do not want to commit)."
# Optional: print tool table rows for pasting into tool-packages.md
echo ""
echo "--- Tool package rows (markdown) ---"
for d in "$ROOT/src/tools"/*/; do
[[ -d "$d" ]] || continue
b=$(basename "$d")
echo "| \`$b\` | \`src/tools/$b/\` |"
done | sort