diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index dfe0770..0000000 --- a/.gitattributes +++ /dev/null @@ -1,2 +0,0 @@ -# Auto detect text files and perform LF normalization -* text=auto diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml deleted file mode 100644 index 38de4ae..0000000 --- a/.github/workflows/pages.yml +++ /dev/null @@ -1,44 +0,0 @@ -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/docs-site/.gitignore b/docs-site/.gitignore deleted file mode 100644 index 5bf6b79..0000000 --- a/docs-site/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -.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 deleted file mode 100644 index 53ec4df..0000000 --- a/docs-site/docs/appendix/directory-structure.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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 deleted file mode 100644 index 7140afb..0000000 --- a/docs-site/docs/appendix/environment-variables.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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/glossary.md b/docs-site/docs/appendix/glossary.md deleted file mode 100644 index 9eb49e7..0000000 --- a/docs-site/docs/appendix/glossary.md +++ /dev/null @@ -1,20 +0,0 @@ -# Glossary - -Short definitions for terms used across this site and the `src/` tree. Authoritative product wording remains in [official Claude Code docs](https://code.claude.com/docs/en/overview). - -| Term | Meaning (in this codebase) | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| **Agent / teammate** | Secondary model actors coordinated with the main session; implemented largely in `utils/swarm/`. | -| **Compaction** | Reducing or rewriting transcript/history to fit context limits; `services/compact/`. | -| **Coordinator** | Internal multi-agent coordination feature gated by `COORDINATOR_MODE`; `coordinator/`. | -| **GrowthBook** | Feature-flag / experiment client for product behaviors; `services/analytics/growthbook.ts`. | -| **Headless / print** | Non-TUI mode with structured stdin/stdout; `cli/print.ts`, `QueryEngine.ts`. | -| **KAIROS** | Bundle-time gate for assistant-oriented code paths; `assistant/`. | -| **MCP** | Model Context Protocol; `services/mcp/`, MCP tools under `tools/`. | -| **REPL** | Interactive terminal UI session; `screens/REPL.tsx`. | -| **Session hooks** | User-configured shell hooks on lifecycle events; see `utils/sessionStart.ts` and official [Hooks](https://code.claude.com/docs/en/hooks). | -| **Swarm** | Implementation umbrella for teammate spawning (tmux, iTerm, in-process); `utils/swarm/`. | -| **Teleport** | Session handoff / remote resume flows; `utils/teleport/`, related API modules. | -| **Tool loop** | Alternation between model streaming and tool execution until the turn completes; centered on `query.ts`. | -| **Trust** | User acknowledgement of workspace risk before applying project config; wired from `main.tsx` / config utilities. | -| **VOICE_MODE** | Compile-time gate for voice dictation in the REPL; `voice/`. | diff --git a/docs-site/docs/appendix/tool-packages.md b/docs-site/docs/appendix/tool-packages.md deleted file mode 100644 index faf2054..0000000 --- a/docs-site/docs/appendix/tool-packages.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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 deleted file mode 100644 index 3fc389c..0000000 --- a/docs-site/docs/architecture.md +++ /dev/null @@ -1,76 +0,0 @@ -# Architecture overview - -!!! 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 -``` - -## System design (deeper dives) - -| Topic | Page | -| --------------------------------- | ----------------------------------------------------------------- | -| Layering and dependency direction | [Architectural layers](system-design/layers.md) | -| State, messages, and persistence | [State and data flow](system-design/state-and-data-flow.md) | -| Trust, permissions, MCP policy | [Security and trust model](system-design/security-trust-model.md) | - -## Short orientation - -- **Entry** — `main.tsx`: Commander CLI, `preAction` (trust, settings, telemetry gates), side-effect imports (profiler, MDM, keychain prefetch). -- **Interactive host** — `replLauncher.tsx`, `screens/REPL.tsx`, `utils/queueProcessor.ts`. -- **Headless host** — `cli/print.ts`, `QueryEngine.ts`, `cli/structuredIO.ts`. -- **Tools & MCP** — `tools.ts`, `tools/*`, `services/mcp/`, `services/tools/`. -- **IDE / OS** — `bridge/`, `utils/deepLink/`, `utils/claudeInChrome/`. - -## 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 | - -## Further reading - -- [Workflows](workflows.md) — end-to-end sequences. -- [Official docs map](official-docs-map.md) — product docs ↔ `src/`. -- [Reference](reference/cli-entry.md) — subsystem reference pages. -- [Glossary](appendix/glossary.md). diff --git a/docs-site/docs/developer/bun-bundle-and-feature-flags.md b/docs-site/docs/developer/bun-bundle-and-feature-flags.md deleted file mode 100644 index 8579d14..0000000 --- a/docs-site/docs/developer/bun-bundle-and-feature-flags.md +++ /dev/null @@ -1,26 +0,0 @@ -# Bun bundle and feature flags - -The shipping Claude Code CLI is built with **Bun** and internal **`bun:bundle`** integration. In the recovered source, `src/main.tsx` uses compile-time feature gates such as: - -- `feature('KAIROS')` — lazy `require` of `assistant/` (assistant / Agent SDK–oriented paths). -- `feature('COORDINATOR_MODE')` — lazy `require` of `coordinator/coordinatorMode`. -- `feature('VOICE_MODE')` — conditional `useVoiceIntegration` in `REPL.tsx`. - -## What `feature()` means here - -In Anthropic’s pipeline, `feature('…')` is almost certainly a **constant** resolved at bundle time: dead branches are stripped from the published `cli.js`. The reconstruction **contains all branches** as TypeScript, so you can read “internal” code paths that might not ship in every npm artifact. - -## Implications for “building from source” - -A normal `tsc` or `bun build` **without** Anthropic’s bundler will not reproduce: - -- The same dead-code elimination. -- The same `bun:bundle` API semantics. -- The same proprietary dependency closure. - -That is one reason [Reproducibility and limits](../reproducibility.md) states you cannot rebuild the shipping binary from this mirror. - -## See also - -- [System design: layers](../system-design/layers.md) -- [CLI entry reference](../reference/cli-entry.md) diff --git a/docs-site/docs/developer/editing-documentation.md b/docs-site/docs/developer/editing-documentation.md deleted file mode 100644 index 50baf7a..0000000 --- a/docs-site/docs/developer/editing-documentation.md +++ /dev/null @@ -1,29 +0,0 @@ -# Editing this documentation - -## Local setup - -```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` and edit files under `docs-site/docs/`. The site reloads on save. - -## Conventions - -- Use **admonitions** for legal and safety notes (`!!! warning` for proprietary / leak context). -- Prefer **relative links** between pages (`../reference/cli-entry.md` in source becomes sibling URLs when built). -- Add **mermaid** only where diagrams clarify flow; keep [mermaid syntax](https://mermaid.js.org/) compatible with [Material diagrams](https://squidfunk.github.io/mkdocs-material/reference/diagrams/). - -## After structural changes - -If you add a **new top-level topic** that appears in [Anthropic’s docs index](https://code.claude.com/docs/llms.txt), add a row to [Official docs map](../official-docs-map.md). - -## Publishing - -Pushing to `main` runs the GitHub Action that deploys to `gh-pages`. Ensure `site_url` in `mkdocs.yml` matches your GitHub Pages base URL. - -See also: [Documentation and CI for your own projects](../guides/documentation-and-ci-for-docs.md). diff --git a/docs-site/docs/developer/index.md b/docs-site/docs/developer/index.md deleted file mode 100644 index ff3f763..0000000 --- a/docs-site/docs/developer/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Developer hub (this repository) - -!!! warning "Not an open-source product repo" -This tree is **reconstructed proprietary source**. You can maintain **documentation**, trace **read-only** flow in `src/`, and run small **helper scripts**. You **cannot** legally ship Claude Code from this mirror, and there is no supported way to compile the full CLI here. - -## What you can do - -| Activity | How | -| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Preview or extend docs** | [Editing documentation](editing-documentation.md) | -| **Understand control flow** | [Navigating the source](navigating-the-source.md) | -| **Learn build-time gates** | [Bun bundle and feature flags](bun-bundle-and-feature-flags.md) | -| **Regenerate appendix data** | `scripts/gen-appendices.sh` at repo root (see [Appendix: environment variables](../appendix/environment-variables.md)) | - -## What you cannot do (from this mirror alone) - -- Run `npm install` / `bun build` for the full product (no root `package.json`, private graph, `bun:bundle` feature flags). -- Execute a project-wide automated test suite for the CLI (no harness shipped in the reconstruction). - -Details: [Reproducibility and limits](../reproducibility.md). - -## Related - -- [System design: layers](../system-design/layers.md) -- [Official docs map](../official-docs-map.md) diff --git a/docs-site/docs/developer/navigating-the-source.md b/docs-site/docs/developer/navigating-the-source.md deleted file mode 100644 index 1d91aba..0000000 --- a/docs-site/docs/developer/navigating-the-source.md +++ /dev/null @@ -1,37 +0,0 @@ -# Navigating the `src/` tree - -!!! warning "Read-only study" -Use this guide to **read** the reconstruction. Do not treat the tree as a template for redistributing Anthropic’s product. - -## Suggested reading order - -1. **`main argv` and lifecycle** — `src/main.tsx` (Commander, `preAction`, mode routing). -2. **Interactive path** — `src/replLauncher.tsx`, `src/screens/REPL.tsx` (queue, `onQuery`, UI). -3. **Headless path** — `src/cli/print.ts`, `src/cli/structuredIO.ts`, `src/QueryEngine.ts`. -4. **Core loop** — `src/query.ts` (`queryLoop`), then `src/services/api/client.ts` / `claude.ts`. -5. **Tools** — `src/tools.ts`, `src/Tool.ts`, then a single tool package e.g. `src/tools/BashTool/` and `src/services/tools/`. -6. **MCP** — `src/services/mcp/` and `src/tools/MCPTool/`. - -## Maps and indexes - -- Top-level layout: [Appendix: directory structure](../appendix/directory-structure.md) (and repo `docs/directory-structure.md`). -- Tool packages: [Appendix: tool packages](../appendix/tool-packages.md). -- Official doc crosswalk: [Official docs map](../official-docs-map.md). - -## Search tips - -From the repository root: - -```bash -# Example: find where a symbol is used -rg "queryLoop" src/query.ts src/ -n - -# Example: MCP channel permissions -rg "channelAllowlist" src/services/mcp -n -``` - -IDE “go to definition” may be incomplete: there is **no** root `tsconfig.json` or `package.json` mirroring Anthropic’s build, so path aliases like `src/...` might not resolve everywhere. - -## Deeper subsystems - -Use the [Reference](../reference/cli-entry.md) section for per-topic entry points (permissions, compaction, telemetry, bridge, etc.). diff --git a/docs-site/docs/guides/building-an-agentic-cli-overview.md b/docs-site/docs/guides/building-an-agentic-cli-overview.md deleted file mode 100644 index 0430e86..0000000 --- a/docs-site/docs/guides/building-an-agentic-cli-overview.md +++ /dev/null @@ -1,39 +0,0 @@ -# Building your own agentic coding CLI (greenfield) - -!!! danger "Do not clone proprietary code" -This page describes how to build **new** tooling from **public** APIs and OSS patterns. It is **not** instructions to copy or redistribute the leaked `src/` tree as “open-source Claude Code.” Anthropic’s Claude Code remains **proprietary**. - -## What “agentic CLI” means - -A minimal agent loop: - -1. **Context** — project files, git status, user prompt. -2. **Model** — calls a capable LLM API with tools/functions defined in schema form. -3. **Tools** — read/write files, grep, run shell (with guardrails), call HTTP, etc. -4. **Loop** — model requests tools → host executes → results appended → model continues until done. - -Claude Code implements this pattern in TypeScript with extra product layers (trust, compaction, MCP, IDE bridge). Your project can be far smaller. - -## Stack options (all legitimate OSS / vendor SDKs) - -| Piece | Common choices | -| ----------------- | -------------------------------------------------------------------------------------------------------------------- | -| **Runtime** | Node.js, Bun, Deno, Go, Python | -| **Terminal UI** | None (pure stdin/stdout), [Ink](https://github.com/vadimdemedes/ink) (React), blessed, bubbletea | -| **CLI parsing** | Commander, yargs, clap (Rust), Typer (Python) | -| **Anthropic API** | Official [Anthropic SDK](https://docs.anthropic.com/) and [Messages API](https://docs.anthropic.com/en/api/messages) | -| **MCP** | [Model Context Protocol](https://modelcontextprotocol.io) SDKs and server examples | -| **Sandboxes** | Containers, `firejail`, allow-listed commands, separate VMs (depends on threat model) | - -## OSS / public projects to study (examples, not endorsements) - -Look for **actively maintained** agent or coding assistants under licenses you accept. Examples people often cite in the ecosystem include **Aider**, terminal agents built on **Continue** or **Codex-style** CLIs, and **MCP servers** in the official registry. **Compare licenses and security posture yourself**—do not assume parity with Claude Code. - -## Relationship to this repository - -Use the `src/` mirror to **learn patterns** (how compaction, MCP, or permissions _can_ be structured). Re-implement ideas in **your own codebase** with your own naming and design; do not paste Anthropic’s source into a public repo. - -## Next - -- [MCP and tool-loop patterns](mcp-and-tool-loop-patterns.md) — abstract loop without copying this tree. -- [Documentation and CI](documentation-and-ci-for-docs.md) — ship docs like this site. diff --git a/docs-site/docs/guides/documentation-and-ci-for-docs.md b/docs-site/docs/guides/documentation-and-ci-for-docs.md deleted file mode 100644 index b418656..0000000 --- a/docs-site/docs/guides/documentation-and-ci-for-docs.md +++ /dev/null @@ -1,29 +0,0 @@ -# Documentation and CI (pattern from this repo) - -You can reuse the **same mechanics** this project uses for **any** open-source or internal project docs—not Claude Code itself. - -## Ingredients - -| Piece | Location here | -| --------------- | --------------------------------------------------------------------------------------------------------------------- | -| **Static site** | [MkDocs](https://www.mkdocs.org/) + [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) | -| **Sources** | `docs-site/docs/**/*.md`, `docs-site/mkdocs.yml` | -| **Build** | `mkdocs build -f docs-site/mkdocs.yml` | -| **Deploy** | GitHub Actions → `gh-pages` branch (e.g. [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)) | - -## Checklist for a new repo - -1. Add `docs-site/` with `mkdocs.yml`, `requirements.txt`, and Markdown under `docs/`. -2. Set `site_url` when GitHub Pages URL is known. -3. Add workflow: Python setup → `pip install -r docs-site/requirements.txt` → `mkdocs build` → deploy `docs-site/site`. -4. Enable **GitHub Pages** from `gh-pages` / root (or switch to GitHub’s native Pages Actions upload). -5. Use `enable_jekyll: false` (or commit `.nojekyll`) so Jekyll does not skip underscore paths. - -## This fork’s live site - -Configured `site_url`: [https://mehmoodosman.github.io/claude-code-source-code/](https://mehmoodosman.github.io/claude-code-source-code/) - -## See also - -- [Installation](../installation.md) — local preview commands -- [Editing documentation](../developer/editing-documentation.md) diff --git a/docs-site/docs/guides/mcp-and-tool-loop-patterns.md b/docs-site/docs/guides/mcp-and-tool-loop-patterns.md deleted file mode 100644 index c5110be..0000000 --- a/docs-site/docs/guides/mcp-and-tool-loop-patterns.md +++ /dev/null @@ -1,31 +0,0 @@ -# MCP and tool-loop patterns (abstract) - -!!! note "Conceptual only" -This page describes **common agent architectures**. It references `src/` modules only as **illustrations** of where similar ideas appear in Claude Code—not as code to copy. - -## Tool loop (functions / tools) - -1. Define tools with **names, descriptions, and JSON Schema** (or equivalent) for arguments. -2. Send user + conversation + tool definitions to the model. -3. If the model returns a **tool call**, validate arguments, **execute** on the host, append a **tool_result** message (or provider-specific equivalent). -4. Repeat until the model finishes without further tool calls or a cap is hit. - -In this reconstruction, much of that orchestration lives in `query.ts` and adjacent helpers, while tool implementations live under `tools/*` and `services/tools/`. - -## MCP (Model Context Protocol) - -**MCP** standardizes how tools and resources are exposed by **servers** the host spawns and talks to over stdio or other transports. Claude Code’s `services/mcp/` implements configuration, transports, OAuth, and channel-style push—see **[MCP reference](../reference/mcp.md)** for file-level mapping. - -For **your** project: - -- Start from [MCP documentation](https://modelcontextprotocol.io) and official SDKs. -- Implement **one** small MCP server (e.g. filesystem or git) before designing a full IDE-quality integration. - -## Parallel: skills and plugins - -Claude Code layers **skills** (project-scoped instructions + commands) and **plugins** on top of the core loop. Greenfield designs might use: simple slash-commands, `SKILL.md` conventions, or dynamic imports—without reproducing this product’s plugin manifest. - -## See also - -- [Building an agentic CLI overview](building-an-agentic-cli-overview.md) -- [Official: MCP](https://code.claude.com/docs/en/mcp) diff --git a/docs-site/docs/index.md b/docs-site/docs/index.md deleted file mode 100644 index a5500fa..0000000 --- a/docs-site/docs/index.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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. | -| [System design](system-design/layers.md) | Layers, state/data flow, security and trust model. | -| [Architecture](architecture.md) | Overview diagram and links into system design + reference. | -| [Workflows](workflows.md) | Interactive REPL, print/headless, swarm, compaction paths. | -| [Developer hub](developer/index.md) | Working on docs, navigating `src/`, Bun feature flags. | -| [Guides](guides/building-an-agentic-cli-overview.md) | **Greenfield** agentic CLI and docs/CI patterns—not cloning this leak. | -| [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, [glossary](appendix/glossary.md). | - -## Repository - -Source code lives under `src/` on GitHub ([mehmoodosman/claude-code-source-code](https://github.com/mehmoodosman/claude-code-source-code)). This site is published at **[https://mehmoodosman.github.io/claude-code-source-code/](https://mehmoodosman.github.io/claude-code-source-code/)** via GitHub Actions from `docs-site/`. diff --git a/docs-site/docs/installation.md b/docs-site/docs/installation.md deleted file mode 100644 index 5e58392..0000000 --- a/docs-site/docs/installation.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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. Set `site_url` in `mkdocs.yml` to your real Pages URL (this fork uses `https://mehmoodosman.github.io/claude-code-source-code/`) and keep `repo_url` aligned with your GitHub owner so “edit” links and sitemaps stay correct. - -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 deleted file mode 100644 index 49f10f8..0000000 --- a/docs-site/docs/official-docs-map.md +++ /dev/null @@ -1,154 +0,0 @@ -# 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 deleted file mode 100644 index 81d3399..0000000 --- a/docs-site/docs/reference/api-client.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 deleted file mode 100644 index d63f928..0000000 --- a/docs-site/docs/reference/cli-entry.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index dd560ee..0000000 --- a/docs-site/docs/reference/compaction.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 deleted file mode 100644 index 734461b..0000000 --- a/docs-site/docs/reference/lsp.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 deleted file mode 100644 index 1183d21..0000000 --- a/docs-site/docs/reference/mcp.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index ceef36e..0000000 --- a/docs-site/docs/reference/permissions.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 deleted file mode 100644 index 319e26d..0000000 --- a/docs-site/docs/reference/plugins-skills.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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 deleted file mode 100644 index 9930363..0000000 --- a/docs-site/docs/reference/print-sdk.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index 347e4c1..0000000 --- a/docs-site/docs/reference/query-engine.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index c278de8..0000000 --- a/docs-site/docs/reference/remote-bridge.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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 deleted file mode 100644 index 445eacf..0000000 --- a/docs-site/docs/reference/repl-ui.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index 8a88adf..0000000 --- a/docs-site/docs/reference/settings-policy.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index 2bb66f4..0000000 --- a/docs-site/docs/reference/telemetry.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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 deleted file mode 100644 index 2c11afd..0000000 --- a/docs-site/docs/reference/tools.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index 447ddd3..0000000 --- a/docs-site/docs/reference/voice-vim-output.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 deleted file mode 100644 index dc6d2a5..0000000 --- a/docs-site/docs/reproducibility.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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/system-design/layers.md b/docs-site/docs/system-design/layers.md deleted file mode 100644 index 9cc9ffe..0000000 --- a/docs-site/docs/system-design/layers.md +++ /dev/null @@ -1,68 +0,0 @@ -# Architectural layers - -!!! warning "Recovered proprietary source" -Descriptions are for **study** of the `src/` mirror only. This is not an open-source distribution of Claude Code. - -The Claude Code CLI is organized as **downward dependencies**: the shell and UI call into the query core and services; core logic does not depend on React/Ink components for correctness (headless paths prove that). - -## Layer stack (conceptual) - -| Layer | Responsibility | Primary `src/` locations | -| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -| **CLI shell** | argv parsing, global flags, subcommands, `preAction` startup | `main.tsx`, `commands/`, `cli/handlers/` | -| **Session host** | Interactive TUI vs structured print/SDK transport | `replLauncher.tsx`, `screens/REPL.tsx`, `cli/print.ts`, `cli/structuredIO.ts` | -| **Query core** | Turn loop, streaming, tool round-trips, context assembly | `query.ts`, `QueryEngine.ts`, `utils/processUserInput/` | -| **Transport** | Anthropic (and provider) HTTP/streaming | `services/api/` | -| **Tooling** | Registry, execution, hooks | `tools.ts`, `Tool.ts`, `tools/*`, `services/tools/` | -| **Integrations** | MCP, LSP, OAuth, IDE bridge | `services/mcp/`, `services/lsp/`, `services/oauth/`, `bridge/` | -| **Policy & persistence** | Settings, compaction, session storage, telemetry | `utils/settings/`, `services/compact/`, `utils/sessionStorage.ts`, `services/analytics/` | - -## Dependency direction - -```mermaid -flowchart TB - subgraph presentation [Presentation] - Main[main.tsx] - REPL[REPL.tsx] - Print[cli/print.ts] - end - subgraph domain [Domain_core] - Query[query.ts] - QE[QueryEngine.ts] - end - subgraph ports [Ports] - API[services/api] - Tools[tools plus services/tools] - MCP[services/mcp] - end - subgraph infra [Infrastructure] - Settings[utils/settings] - Compact[services/compact] - Store[sessionStorage] - end - Main --> REPL - Main --> Print - REPL --> Query - Print --> QE - Query --> API - Query --> Tools - QE --> API - QE --> Tools - Tools --> MCP - Query --> Compact - QE --> Compact - Query --> Settings - Main --> Settings -``` - -**Rule of thumb:** `components/` and `ink/` sit under the REPL branch; `cli/print.ts` bypasses most of that stack but still shares `QueryEngine`, tools, API, and compaction. - -## Feature gates - -Some “layers” exist only in certain shipping builds: `assistant/` (KAIROS), `coordinator/` (`COORDINATOR_MODE`), voice (`VOICE_MODE`). See [Bun bundle and feature flags](../developer/bun-bundle-and-feature-flags.md). - -## See also - -- [State and data flow](state-and-data-flow.md) -- [Security and trust model](security-trust-model.md) -- [Architecture overview](../architecture.md) diff --git a/docs-site/docs/system-design/security-trust-model.md b/docs-site/docs/system-design/security-trust-model.md deleted file mode 100644 index 3e4d196..0000000 --- a/docs-site/docs/system-design/security-trust-model.md +++ /dev/null @@ -1,60 +0,0 @@ -# Security and trust model - -!!! warning "Recovered proprietary source" -This page summarizes **code structure**, not a formal security audit. Follow [official Security](https://code.claude.com/docs/en/security) and [Permissions](https://code.claude.com/docs/en/permissions) guidance for the product. - -## Trust and workspace - -Before destructive work runs, startup paths in `main.tsx` consult trust and workspace state (global config helpers under `utils/config.ts`, managed env under `utils/managedEnv.ts`). The intent is to avoid applying repo-supplied config or hooks until the user has acknowledged risk—public discussion of past ordering bugs is summarized in vendor advisories; always run an **up-to-date** official Claude Code build for production use. - -## Permission modes - -`utils/permissions/` defines modes (manual approval, auto with classifiers, plan-only variants, etc.). `permissionSetup.ts` and related modules: - -- Parse CLI flags (`--permission-mode`, internal aliases). -- Strip or gate “dangerous” capabilities when using auto mode. -- Feed **always-allow** tool lists into `toolPermissionContext`. - -User-facing reference: [Permission modes](https://code.claude.com/docs/en/permission-modes). - -## Bash and sandboxing - -Shell execution flows through `utils/shell/` (bash and PowerShell providers, output limits, read-only validation) and `tools/BashTool/`. Enterprise and product docs describe [Sandboxing](https://code.claude.com/docs/en/sandboxing) behavior; the source tree implements isolation and validation at the tool layer. - -## MCP and enterprise policy - -- **Config** — `services/mcp/config.ts` parses MCP server lists, env expansion, deduplication, and enterprise allowlists. -- **Channels** — `services/mcp/channelAllowlist.ts` and related modules gate inbound push notifications. - -Official: [MCP](https://code.claude.com/docs/en/mcp), [Channels](https://code.claude.com/docs/en/channels). - -## Hooks - -User-defined hooks (session start, post-tool, etc.) are wired through `utils/sessionStart.ts` and related runners; they execute shell commands with the privileges of the CLI process. Treat untrusted projects as **untrusted code** until you understand hook content. - -Official: [Hooks](https://code.claude.com/docs/en/hooks). - -## Trust check order (conceptual) - -```mermaid -flowchart TD - start[Process_start] - config[Load_safe_config_order] - trust[Workspace_trust] - perms[Permission_mode_setup] - hooks[Session_hooks] - tools[Tool_execution] - start --> config - config --> trust - trust --> perms - perms --> hooks - hooks --> tools -``` - -Exact ordering evolves by version; correlate with `main.tsx` `preAction` and `entrypoints/init` when reading the mirror. - -## See also - -- [Permissions reference](../reference/permissions.md) -- [MCP reference](../reference/mcp.md) -- [Reproducibility and limits](../reproducibility.md) diff --git a/docs-site/docs/system-design/state-and-data-flow.md b/docs-site/docs/system-design/state-and-data-flow.md deleted file mode 100644 index e75873a..0000000 --- a/docs-site/docs/system-design/state-and-data-flow.md +++ /dev/null @@ -1,50 +0,0 @@ -# State and data flow - -!!! warning "Recovered proprietary source" -For authoritative product behavior, use [official Claude Code docs](https://code.claude.com/docs/en/overview). - -## End-to-end message path (interactive) - -1. **Input** — User text, slash commands, teammate notifications, or task items reach `screens/REPL.tsx`. -2. **Queue** — `utils/queueProcessor.ts` serializes or batches commands and calls `executeInput`. -3. **Query** — `query.ts` `queryLoop` streams the model, surfaces `tool_use` blocks, and applies permission checks using `toolPermissionContext` from app state. -4. **Execution** — `services/tools/` (e.g. `StreamingToolExecutor`, `toolExecution.ts`) dispatches to modules under `tools/*` or MCP-backed tools. -5. **Persistence** — Transcript updates, session metadata, and compaction boundaries flow through `utils/sessionStorage.ts`, conversation recovery helpers, and related hooks. - -## State ownership - -| Concern | Typical modules | -| ----------------------- | ------------------------------------------------------------------------------------------ | -| **Global app state** | `state/` (providers, stores such as `AppStateStore.ts`) | -| **Context / stats** | `context/` | -| **Messages** | `utils/messages.ts`, message types under `types/message` (and generated types) | -| **Permissions** | `utils/permissions/`, fields on tool permission context updated from CLI and REPL | -| **File / edit history** | Wired through process-user-input and tool hooks (see compaction and attribution utilities) | - -## Simplified sequence (one turn) - -```mermaid -sequenceDiagram - participant UI as REPL_or_print - participant Q as queryLoop - participant API as services_api - participant Exec as tool_executor - participant Store as session_storage - UI->>Q: user_or_control_messages - Q->>API: stream_completion - API-->>Q: assistant_tool_use - Q->>Exec: run_tool - Exec-->>Q: tool_result - Q->>Store: persist_transcript_updates - Q-->>UI: render_updates -``` - -## Headless differences - -In print/SDK paths: `QueryEngine.ts` builds a `processUserInputContext` with `isNonInteractiveSession: true`, streams SDK-style messages, and bridges permission prompts over structured I/O instead of Ink dialogs. The **same** underlying message and tool model is reused. - -## See also - -- [Workflows](../workflows.md) -- [Query loop and streaming](../reference/query-engine.md) -- [Compaction](../reference/compaction.md) diff --git a/docs-site/docs/workflows.md b/docs-site/docs/workflows.md deleted file mode 100644 index 86cfd04..0000000 --- a/docs-site/docs/workflows.md +++ /dev/null @@ -1,83 +0,0 @@ -# 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 -``` - -## See also - -- [Architecture overview](architecture.md) -- [State and data flow](system-design/state-and-data-flow.md) -- [Official docs map](official-docs-map.md) diff --git a/docs-site/mkdocs.yml b/docs-site/mkdocs.yml deleted file mode 100644 index 0c78a25..0000000 --- a/docs-site/mkdocs.yml +++ /dev/null @@ -1,100 +0,0 @@ -site_url: https://mehmoodosman.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 - -repo_url: https://github.com/mehmoodosman/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 - - System design: - - system-design/layers.md - - system-design/state-and-data-flow.md - - system-design/security-trust-model.md - - Architecture: - - architecture.md - - workflows.md - - Developer: - - developer/index.md - - developer/editing-documentation.md - - developer/navigating-the-source.md - - developer/bun-bundle-and-feature-flags.md - - Guides: - - guides/building-an-agentic-cli-overview.md - - guides/mcp-and-tool-loop-patterns.md - - guides/documentation-and-ci-for-docs.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 - - appendix/glossary.md - -plugins: - - search - -extra: - social: - - icon: fontawesome/brands/github - link: https://github.com/mehmoodosman/claude-code-source-code diff --git a/docs-site/requirements.txt b/docs-site/requirements.txt deleted file mode 100644 index 9331606..0000000 --- a/docs-site/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -mkdocs-material>=9.5.0,<10 diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 59f3785..0000000 --- a/docs/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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**. - -The published site also includes **System design**, **Developer**, **Guides** (greenfield agent CLI + docs CI), and **Glossary**; see navigation in `docs-site/mkdocs.yml`. diff --git a/docs/directory-structure.md b/docs/directory-structure.md deleted file mode 100644 index 0500b9f..0000000 --- a/docs/directory-structure.md +++ /dev/null @@ -1,78 +0,0 @@ -# `src/` directory structure - -This document mirrors the **top levels** of the recovered `src/` tree in this repository (as of the leak reconstruction). Deeper nesting is omitted except where it helps navigation. - -## 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, for example: `BashTool`, `FileReadTool`, `FileWriteTool`, `FileEditTool`, `GlobTool`, `GrepTool`, `WebSearchTool`, `WebFetchTool`, `MCPTool`, `AgentTool`, `TodoWriteTool`, `TaskCreateTool`, `TaskListTool`, `EnterWorktreeTool`, `ExitWorktreeTool`, `LSPTool`, `SkillTool`, `REPLTool`, … plus `shared/` and `testing/`. - -## `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/scripts/gen-appendices.sh b/scripts/gen-appendices.sh deleted file mode 100755 index 30dc9a3..0000000 --- a/scripts/gen-appendices.sh +++ /dev/null @@ -1,26 +0,0 @@ -#!/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