From 9024f81eb7a13ef3750ab0160f1e15a9a96feff2 Mon Sep 17 00:00:00 2001 From: Osman Mehmood <88900308+mehmoodosman@users.noreply.github.com> Date: Tue, 31 Mar 2026 15:38:58 +0500 Subject: [PATCH] add documentation --- .github/workflows/pages.yml | 44 +++++ .gitignore | 4 +- README.md | 26 ++- docs-site/.gitignore | 3 + .../docs/appendix/directory-structure.md | 78 +++++++++ .../docs/appendix/environment-variables.md | 41 +++++ docs-site/docs/appendix/tool-packages.md | 50 ++++++ docs-site/docs/architecture.md | 93 +++++++++++ docs-site/docs/index.md | 30 ++++ docs-site/docs/installation.md | 36 ++++ docs-site/docs/official-docs-map.md | 154 ++++++++++++++++++ docs-site/docs/reference/api-client.md | 9 + docs-site/docs/reference/cli-entry.md | 11 ++ docs-site/docs/reference/compaction.md | 9 + docs-site/docs/reference/lsp.md | 9 + docs-site/docs/reference/mcp.md | 11 ++ docs-site/docs/reference/permissions.md | 9 + docs-site/docs/reference/plugins-skills.md | 9 + docs-site/docs/reference/print-sdk.md | 11 ++ docs-site/docs/reference/query-engine.md | 11 ++ docs-site/docs/reference/remote-bridge.md | 13 ++ docs-site/docs/reference/repl-ui.md | 11 ++ docs-site/docs/reference/settings-policy.md | 11 ++ docs-site/docs/reference/telemetry.md | 7 + docs-site/docs/reference/tools.md | 11 ++ docs-site/docs/reference/voice-vim-output.md | 11 ++ docs-site/docs/reproducibility.md | 32 ++++ docs-site/docs/workflows.md | 77 +++++++++ docs-site/mkdocs.yml | 87 ++++++++++ docs-site/requirements.txt | 1 + docs/README.md | 8 + scripts/gen-appendices.sh | 26 +++ 32 files changed, 941 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/pages.yml create mode 100644 docs-site/.gitignore create mode 100644 docs-site/docs/appendix/directory-structure.md create mode 100644 docs-site/docs/appendix/environment-variables.md create mode 100644 docs-site/docs/appendix/tool-packages.md create mode 100644 docs-site/docs/architecture.md create mode 100644 docs-site/docs/index.md create mode 100644 docs-site/docs/installation.md create mode 100644 docs-site/docs/official-docs-map.md create mode 100644 docs-site/docs/reference/api-client.md create mode 100644 docs-site/docs/reference/cli-entry.md create mode 100644 docs-site/docs/reference/compaction.md create mode 100644 docs-site/docs/reference/lsp.md create mode 100644 docs-site/docs/reference/mcp.md create mode 100644 docs-site/docs/reference/permissions.md create mode 100644 docs-site/docs/reference/plugins-skills.md create mode 100644 docs-site/docs/reference/print-sdk.md create mode 100644 docs-site/docs/reference/query-engine.md create mode 100644 docs-site/docs/reference/remote-bridge.md create mode 100644 docs-site/docs/reference/repl-ui.md create mode 100644 docs-site/docs/reference/settings-policy.md create mode 100644 docs-site/docs/reference/telemetry.md create mode 100644 docs-site/docs/reference/tools.md create mode 100644 docs-site/docs/reference/voice-vim-output.md create mode 100644 docs-site/docs/reproducibility.md create mode 100644 docs-site/docs/workflows.md create mode 100644 docs-site/mkdocs.yml create mode 100644 docs-site/requirements.txt create mode 100644 docs/README.md create mode 100755 scripts/gen-appendices.sh diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..38de4ae --- /dev/null +++ b/.github/workflows/pages.yml @@ -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 diff --git a/.gitignore b/.gitignore index 496ee2c..024d6e4 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ -.DS_Store \ No newline at end of file +.DS_Store +docs-site/.venv/ +docs-site/site/ \ No newline at end of file diff --git a/README.md b/README.md index 8a74529..bdbdb74 100644 --- a/README.md +++ b/README.md @@ -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://.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**. diff --git a/docs-site/.gitignore b/docs-site/.gitignore new file mode 100644 index 0000000..5bf6b79 --- /dev/null +++ b/docs-site/.gitignore @@ -0,0 +1,3 @@ +.venv/ +site/ +docs/appendix/_generated-env-vars.txt diff --git a/docs-site/docs/appendix/directory-structure.md b/docs-site/docs/appendix/directory-structure.md new file mode 100644 index 0000000..53ec4df --- /dev/null +++ b/docs-site/docs/appendix/directory-structure.md @@ -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. diff --git a/docs-site/docs/appendix/environment-variables.md b/docs-site/docs/appendix/environment-variables.md new file mode 100644 index 0000000..7140afb --- /dev/null +++ b/docs-site/docs/appendix/environment-variables.md @@ -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. diff --git a/docs-site/docs/appendix/tool-packages.md b/docs-site/docs/appendix/tool-packages.md new file mode 100644 index 0000000..faf2054 --- /dev/null +++ b/docs-site/docs/appendix/tool-packages.md @@ -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. diff --git a/docs-site/docs/architecture.md b/docs-site/docs/architecture.md new file mode 100644 index 0000000..905f2ce --- /dev/null +++ b/docs-site/docs/architecture.md @@ -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). diff --git a/docs-site/docs/index.md b/docs-site/docs/index.md new file mode 100644 index 0000000..b2fa531 --- /dev/null +++ b/docs-site/docs/index.md @@ -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://.github.io//` (see the root `README.md`). diff --git a/docs-site/docs/installation.md b/docs-site/docs/installation.md new file mode 100644 index 0000000..b144cbd --- /dev/null +++ b/docs-site/docs/installation.md @@ -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://.github.io//`) 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. diff --git a/docs-site/docs/official-docs-map.md b/docs-site/docs/official-docs-map.md new file mode 100644 index 0000000..49f10f8 --- /dev/null +++ b/docs-site/docs/official-docs-map.md @@ -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` | + + + +<｜tool▁calls▁begin｜><｜tool▁call▁begin｜> +Read diff --git a/docs-site/docs/reference/api-client.md b/docs-site/docs/reference/api-client.md new file mode 100644 index 0000000..81d3399 --- /dev/null +++ b/docs-site/docs/reference/api-client.md @@ -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). diff --git a/docs-site/docs/reference/cli-entry.md b/docs-site/docs/reference/cli-entry.md new file mode 100644 index 0000000..d63f928 --- /dev/null +++ b/docs-site/docs/reference/cli-entry.md @@ -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). diff --git a/docs-site/docs/reference/compaction.md b/docs-site/docs/reference/compaction.md new file mode 100644 index 0000000..dd560ee --- /dev/null +++ b/docs-site/docs/reference/compaction.md @@ -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). diff --git a/docs-site/docs/reference/lsp.md b/docs-site/docs/reference/lsp.md new file mode 100644 index 0000000..734461b --- /dev/null +++ b/docs-site/docs/reference/lsp.md @@ -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). diff --git a/docs-site/docs/reference/mcp.md b/docs-site/docs/reference/mcp.md new file mode 100644 index 0000000..1183d21 --- /dev/null +++ b/docs-site/docs/reference/mcp.md @@ -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). diff --git a/docs-site/docs/reference/permissions.md b/docs-site/docs/reference/permissions.md new file mode 100644 index 0000000..ceef36e --- /dev/null +++ b/docs-site/docs/reference/permissions.md @@ -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). diff --git a/docs-site/docs/reference/plugins-skills.md b/docs-site/docs/reference/plugins-skills.md new file mode 100644 index 0000000..319e26d --- /dev/null +++ b/docs-site/docs/reference/plugins-skills.md @@ -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). diff --git a/docs-site/docs/reference/print-sdk.md b/docs-site/docs/reference/print-sdk.md new file mode 100644 index 0000000..9930363 --- /dev/null +++ b/docs-site/docs/reference/print-sdk.md @@ -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). diff --git a/docs-site/docs/reference/query-engine.md b/docs-site/docs/reference/query-engine.md new file mode 100644 index 0000000..347e4c1 --- /dev/null +++ b/docs-site/docs/reference/query-engine.md @@ -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). diff --git a/docs-site/docs/reference/remote-bridge.md b/docs-site/docs/reference/remote-bridge.md new file mode 100644 index 0000000..c278de8 --- /dev/null +++ b/docs-site/docs/reference/remote-bridge.md @@ -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). diff --git a/docs-site/docs/reference/repl-ui.md b/docs-site/docs/reference/repl-ui.md new file mode 100644 index 0000000..445eacf --- /dev/null +++ b/docs-site/docs/reference/repl-ui.md @@ -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). diff --git a/docs-site/docs/reference/settings-policy.md b/docs-site/docs/reference/settings-policy.md new file mode 100644 index 0000000..8a88adf --- /dev/null +++ b/docs-site/docs/reference/settings-policy.md @@ -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). diff --git a/docs-site/docs/reference/telemetry.md b/docs-site/docs/reference/telemetry.md new file mode 100644 index 0000000..2bb66f4 --- /dev/null +++ b/docs-site/docs/reference/telemetry.md @@ -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). diff --git a/docs-site/docs/reference/tools.md b/docs-site/docs/reference/tools.md new file mode 100644 index 0000000..2c11afd --- /dev/null +++ b/docs-site/docs/reference/tools.md @@ -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). diff --git a/docs-site/docs/reference/voice-vim-output.md b/docs-site/docs/reference/voice-vim-output.md new file mode 100644 index 0000000..447ddd3 --- /dev/null +++ b/docs-site/docs/reference/voice-vim-output.md @@ -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). diff --git a/docs-site/docs/reproducibility.md b/docs-site/docs/reproducibility.md new file mode 100644 index 0000000..dc6d2a5 --- /dev/null +++ b/docs-site/docs/reproducibility.md @@ -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. diff --git a/docs-site/docs/workflows.md b/docs-site/docs/workflows.md new file mode 100644 index 0000000..057886d --- /dev/null +++ b/docs-site/docs/workflows.md @@ -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 +``` diff --git a/docs-site/mkdocs.yml b/docs-site/mkdocs.yml new file mode 100644 index 0000000..791bf1b --- /dev/null +++ b/docs-site/mkdocs.yml @@ -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 diff --git a/docs-site/requirements.txt b/docs-site/requirements.txt new file mode 100644 index 0000000..9331606 --- /dev/null +++ b/docs-site/requirements.txt @@ -0,0 +1 @@ +mkdocs-material>=9.5.0,<10 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..95a2ef8 --- /dev/null +++ b/docs/README.md @@ -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**. diff --git a/scripts/gen-appendices.sh b/scripts/gen-appendices.sh new file mode 100755 index 0000000..30dc9a3 --- /dev/null +++ b/scripts/gen-appendices.sh @@ -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