remove docs for clutter will be it a seperate repo and just add link for full documentation
This commit is contained in:
Osman Mehmood
2
.gitattributes
vendored
2
.gitattributes
vendored
@@ -1,2 +0,0 @@
|
||||
# Auto detect text files and perform LF normalization
|
||||
* text=auto
|
||||
44
.github/workflows/pages.yml
vendored
44
.github/workflows/pages.yml
vendored
@@ -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
|
||||
3
docs-site/.gitignore
vendored
3
docs-site/.gitignore
vendored
@@ -1,3 +0,0 @@
|
||||
.venv/
|
||||
site/
|
||||
docs/appendix/_generated-env-vars.txt
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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/`. |
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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)
|
||||
@@ -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).
|
||||
@@ -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)
|
||||
@@ -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.).
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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/`.
|
||||
@@ -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.
|
||||
@@ -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` |
|
||||
|
||||
</think>
|
||||
|
||||
<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>
|
||||
Read
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -1 +0,0 @@
|
||||
mkdocs-material>=9.5.0,<10
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user