the claude code sourcemaps leaked march 31
add developer docs
+468
-46
+1
-1
README.md
+1
-1
README.md
···
121
121
122
122
## Documentation (GitHub Pages)
123
123
124
-
Full internals documentation (architecture, workflows, official-docs cross-reference, subsystem reference, appendices) is built with **MkDocs Material** from [`docs-site/`](docs-site/).
124
+
Full internals documentation is built with **MkDocs Material** from [`docs-site/`](docs-site/). The site includes **system design** (layers, state flow, security/trust), **architecture** overview and **workflows**, a **developer hub** (editing docs, navigating `src/`, Bun feature flags), **guides** for greenfield agentic CLI and docs/CI patterns, **reference** pages per subsystem, **official docs map**, and **appendices** (directory layout, tools, env vars, glossary).
125
125
126
126
- **Live site:** [https://mehmoodosman.github.io/claude-code-source-code/](https://mehmoodosman.github.io/claude-code-source-code/)
127
127
- **Local preview:** `cd docs-site && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && mkdocs serve`
+20
docs-site/docs/appendix/glossary.md
+20
docs-site/docs/appendix/glossary.md
···
1
+
# Glossary
2
+
3
+
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).
4
+
5
+
| Term | Meaning (in this codebase) |
6
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
7
+
| **Agent / teammate** | Secondary model actors coordinated with the main session; implemented largely in `utils/swarm/`. |
8
+
| **Compaction** | Reducing or rewriting transcript/history to fit context limits; `services/compact/`. |
9
+
| **Coordinator** | Internal multi-agent coordination feature gated by `COORDINATOR_MODE`; `coordinator/`. |
10
+
| **GrowthBook** | Feature-flag / experiment client for product behaviors; `services/analytics/growthbook.ts`. |
11
+
| **Headless / print** | Non-TUI mode with structured stdin/stdout; `cli/print.ts`, `QueryEngine.ts`. |
12
+
| **KAIROS** | Bundle-time gate for assistant-oriented code paths; `assistant/`. |
13
+
| **MCP** | Model Context Protocol; `services/mcp/`, MCP tools under `tools/`. |
14
+
| **REPL** | Interactive terminal UI session; `screens/REPL.tsx`. |
15
+
| **Session hooks** | User-configured shell hooks on lifecycle events; see `utils/sessionStart.ts` and official [Hooks](https://code.claude.com/docs/en/hooks). |
16
+
| **Swarm** | Implementation umbrella for teammate spawning (tmux, iTerm, in-process); `utils/swarm/`. |
17
+
| **Teleport** | Session handoff / remote resume flows; `utils/teleport/`, related API modules. |
18
+
| **Tool loop** | Alternation between model streaming and tool execution until the turn completes; centered on `query.ts`. |
19
+
| **Trust** | User acknowledgement of workspace risk before applying project config; wired from `main.tsx` / config utilities. |
20
+
| **VOICE_MODE** | Compile-time gate for voice dictation in the REPL; `voice/`. |
+19
-36
docs-site/docs/architecture.md
+19
-36
docs-site/docs/architecture.md
···
1
-
# Architecture
1
+
# Architecture overview
2
2
3
3
!!! warning "Recovered source"
4
4
Paths refer to `src/` in this repository. Line-level accuracy is best-effort from the source map reconstruction.
···
37
37
qe --> compact
38
38
```
39
39
40
-
## Entry and startup
40
+
## System design (deeper dives)
41
41
42
-
`src/main.tsx` is the **Commander**-based CLI. Before the command handler runs, module evaluation triggers:
43
-
44
-
- Startup profiling checkpoints (`utils/startupProfiler.ts`)
45
-
- MDM raw reads in parallel (`utils/settings/mdm/rawRead.ts`)
46
-
- macOS keychain prefetch (`utils/secureStorage/keychainPrefetch.ts`)
47
-
48
-
The `preAction` hook loads trust, settings, telemetry gates, MCP prefetch, policy limits, and related startup work before interactive or print mode begins.
49
-
50
-
## Interactive mode
42
+
| Topic | Page |
43
+
| --------------------------------- | ----------------------------------------------------------------- |
44
+
| Layering and dependency direction | [Architectural layers](system-design/layers.md) |
45
+
| State, messages, and persistence | [State and data flow](system-design/state-and-data-flow.md) |
46
+
| Trust, permissions, MCP policy | [Security and trust model](system-design/security-trust-model.md) |
51
47
52
-
- `replLauncher.tsx` mounts the Ink/React app.
53
-
- `screens/REPL.tsx` owns the main session UI, input queue, model turns, tool execution UI, teammate hooks, voice (when compiled in), and scheduled-task integration.
54
-
- `utils/queueProcessor.ts` drains slash commands, bash-mode lines, and batched prompts into `executeInput`.
48
+
## Short orientation
55
49
56
-
## Headless / print / SDK-style I/O
57
-
58
-
- `cli/print.ts` implements structured stdin/stdout loops (`runHeadlessStreaming`, NDJSON-style control).
59
-
- `QueryEngine.ts` supports non-REPL paths where messages are submitted programmatically and tool permission context is updated without full UI.
60
-
61
-
## Tools and MCP
62
-
63
-
- `tools.ts` aggregates built-in tools (filtered by permission context) and merges MCP-derived tools.
64
-
- `services/mcp/` implements config parsing, transports, OAuth, channel permissions, and the in-process MCP client used by `MCPConnectionManager` in the UI.
65
-
66
-
## Compaction and memory
67
-
68
-
- `services/compact/` implements context window management aligned with user-facing [context window](https://code.claude.com/docs/en/context-window) and [costs](https://code.claude.com/docs/en/costs) documentation.
69
-
70
-
## Multi-agent (swarm / teammates)
71
-
72
-
- `utils/swarm/` contains backends (tmux, iTerm, in-process), spawn utilities, permission sync, and `inProcessRunner.ts` teammate loop.
73
-
74
-
## IDE integration
75
-
76
-
- `bridge/` plus hooks such as `hooks/useDiffInIDE.ts` connect to VS Code / JetBrains surfaces described in official [VS Code](https://code.claude.com/docs/en/vs-code) and [JetBrains](https://code.claude.com/docs/en/jetbrains) docs.
50
+
- **Entry** — `main.tsx`: Commander CLI, `preAction` (trust, settings, telemetry gates), side-effect imports (profiler, MDM, keychain prefetch).
51
+
- **Interactive host** — `replLauncher.tsx`, `screens/REPL.tsx`, `utils/queueProcessor.ts`.
52
+
- **Headless host** — `cli/print.ts`, `QueryEngine.ts`, `cli/structuredIO.ts`.
53
+
- **Tools & MCP** — `tools.ts`, `tools/*`, `services/mcp/`, `services/tools/`.
54
+
- **IDE / OS** — `bridge/`, `utils/deepLink/`, `utils/claudeInChrome/`.
77
55
78
56
## Key files (quick index)
79
57
···
90
68
| `services/compact/` | Compaction pipeline |
91
69
| `utils/sessionStart.ts` | Session / setup hooks |
92
70
93
-
See also [Workflows](workflows.md) and the [official docs map](official-docs-map.md).
71
+
## Further reading
72
+
73
+
- [Workflows](workflows.md) — end-to-end sequences.
74
+
- [Official docs map](official-docs-map.md) — product docs ↔ `src/`.
75
+
- [Reference](reference/cli-entry.md) — subsystem reference pages.
76
+
- [Glossary](appendix/glossary.md).
+26
docs-site/docs/developer/bun-bundle-and-feature-flags.md
+26
docs-site/docs/developer/bun-bundle-and-feature-flags.md
···
1
+
# Bun bundle and feature flags
2
+
3
+
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:
4
+
5
+
- `feature('KAIROS')` — lazy `require` of `assistant/` (assistant / Agent SDK–oriented paths).
6
+
- `feature('COORDINATOR_MODE')` — lazy `require` of `coordinator/coordinatorMode`.
7
+
- `feature('VOICE_MODE')` — conditional `useVoiceIntegration` in `REPL.tsx`.
8
+
9
+
## What `feature()` means here
10
+
11
+
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.
12
+
13
+
## Implications for “building from source”
14
+
15
+
A normal `tsc` or `bun build` **without** Anthropic’s bundler will not reproduce:
16
+
17
+
- The same dead-code elimination.
18
+
- The same `bun:bundle` API semantics.
19
+
- The same proprietary dependency closure.
20
+
21
+
That is one reason [Reproducibility and limits](../reproducibility.md) states you cannot rebuild the shipping binary from this mirror.
22
+
23
+
## See also
24
+
25
+
- [System design: layers](../system-design/layers.md)
26
+
- [CLI entry reference](../reference/cli-entry.md)
+29
docs-site/docs/developer/editing-documentation.md
+29
docs-site/docs/developer/editing-documentation.md
···
1
+
# Editing this documentation
2
+
3
+
## Local setup
4
+
5
+
```bash
6
+
cd docs-site
7
+
python3 -m venv .venv
8
+
source .venv/bin/activate # Windows: .venv\Scripts\activate
9
+
pip install -r requirements.txt
10
+
mkdocs serve
11
+
```
12
+
13
+
Open `http://127.0.0.1:8000` and edit files under `docs-site/docs/`. The site reloads on save.
14
+
15
+
## Conventions
16
+
17
+
- Use **admonitions** for legal and safety notes (`!!! warning` for proprietary / leak context).
18
+
- Prefer **relative links** between pages (`../reference/cli-entry.md` in source becomes sibling URLs when built).
19
+
- 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/).
20
+
21
+
## After structural changes
22
+
23
+
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).
24
+
25
+
## Publishing
26
+
27
+
Pushing to `main` runs the GitHub Action that deploys to `gh-pages`. Ensure `site_url` in `mkdocs.yml` matches your GitHub Pages base URL.
28
+
29
+
See also: [Documentation and CI for your own projects](../guides/documentation-and-ci-for-docs.md).
+25
docs-site/docs/developer/index.md
+25
docs-site/docs/developer/index.md
···
1
+
# Developer hub (this repository)
2
+
3
+
!!! warning "Not an open-source product repo"
4
+
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.
5
+
6
+
## What you can do
7
+
8
+
| Activity | How |
9
+
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
10
+
| **Preview or extend docs** | [Editing documentation](editing-documentation.md) |
11
+
| **Understand control flow** | [Navigating the source](navigating-the-source.md) |
12
+
| **Learn build-time gates** | [Bun bundle and feature flags](bun-bundle-and-feature-flags.md) |
13
+
| **Regenerate appendix data** | `scripts/gen-appendices.sh` at repo root (see [Appendix: environment variables](../appendix/environment-variables.md)) |
14
+
15
+
## What you cannot do (from this mirror alone)
16
+
17
+
- Run `npm install` / `bun build` for the full product (no root `package.json`, private graph, `bun:bundle` feature flags).
18
+
- Execute a project-wide automated test suite for the CLI (no harness shipped in the reconstruction).
19
+
20
+
Details: [Reproducibility and limits](../reproducibility.md).
21
+
22
+
## Related
23
+
24
+
- [System design: layers](../system-design/layers.md)
25
+
- [Official docs map](../official-docs-map.md)
+39
docs-site/docs/guides/building-an-agentic-cli-overview.md
+39
docs-site/docs/guides/building-an-agentic-cli-overview.md
···
1
+
# Building your own agentic coding CLI (greenfield)
2
+
3
+
!!! danger "Do not clone proprietary code"
4
+
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**.
5
+
6
+
## What “agentic CLI” means
7
+
8
+
A minimal agent loop:
9
+
10
+
1. **Context** — project files, git status, user prompt.
11
+
2. **Model** — calls a capable LLM API with tools/functions defined in schema form.
12
+
3. **Tools** — read/write files, grep, run shell (with guardrails), call HTTP, etc.
13
+
4. **Loop** — model requests tools → host executes → results appended → model continues until done.
14
+
15
+
Claude Code implements this pattern in TypeScript with extra product layers (trust, compaction, MCP, IDE bridge). Your project can be far smaller.
16
+
17
+
## Stack options (all legitimate OSS / vendor SDKs)
18
+
19
+
| Piece | Common choices |
20
+
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
21
+
| **Runtime** | Node.js, Bun, Deno, Go, Python |
22
+
| **Terminal UI** | None (pure stdin/stdout), [Ink](https://github.com/vadimdemedes/ink) (React), blessed, bubbletea |
23
+
| **CLI parsing** | Commander, yargs, clap (Rust), Typer (Python) |
24
+
| **Anthropic API** | Official [Anthropic SDK](https://docs.anthropic.com/) and [Messages API](https://docs.anthropic.com/en/api/messages) |
25
+
| **MCP** | [Model Context Protocol](https://modelcontextprotocol.io) SDKs and server examples |
26
+
| **Sandboxes** | Containers, `firejail`, allow-listed commands, separate VMs (depends on threat model) |
27
+
28
+
## OSS / public projects to study (examples, not endorsements)
29
+
30
+
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.
31
+
32
+
## Relationship to this repository
33
+
34
+
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.
35
+
36
+
## Next
37
+
38
+
- [MCP and tool-loop patterns](mcp-and-tool-loop-patterns.md) — abstract loop without copying this tree.
39
+
- [Documentation and CI](documentation-and-ci-for-docs.md) — ship docs like this site.
+29
docs-site/docs/guides/documentation-and-ci-for-docs.md
+29
docs-site/docs/guides/documentation-and-ci-for-docs.md
···
1
+
# Documentation and CI (pattern from this repo)
2
+
3
+
You can reuse the **same mechanics** this project uses for **any** open-source or internal project docs—not Claude Code itself.
4
+
5
+
## Ingredients
6
+
7
+
| Piece | Location here |
8
+
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
9
+
| **Static site** | [MkDocs](https://www.mkdocs.org/) + [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) |
10
+
| **Sources** | `docs-site/docs/**/*.md`, `docs-site/mkdocs.yml` |
11
+
| **Build** | `mkdocs build -f docs-site/mkdocs.yml` |
12
+
| **Deploy** | GitHub Actions → `gh-pages` branch (e.g. [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)) |
13
+
14
+
## Checklist for a new repo
15
+
16
+
1. Add `docs-site/` with `mkdocs.yml`, `requirements.txt`, and Markdown under `docs/`.
17
+
2. Set `site_url` when GitHub Pages URL is known.
18
+
3. Add workflow: Python setup → `pip install -r docs-site/requirements.txt` → `mkdocs build` → deploy `docs-site/site`.
19
+
4. Enable **GitHub Pages** from `gh-pages` / root (or switch to GitHub’s native Pages Actions upload).
20
+
5. Use `enable_jekyll: false` (or commit `.nojekyll`) so Jekyll does not skip underscore paths.
21
+
22
+
## This fork’s live site
23
+
24
+
Configured `site_url`: [https://mehmoodosman.github.io/claude-code-source-code/](https://mehmoodosman.github.io/claude-code-source-code/)
25
+
26
+
## See also
27
+
28
+
- [Installation](../installation.md) — local preview commands
29
+
- [Editing documentation](../developer/editing-documentation.md)
+31
docs-site/docs/guides/mcp-and-tool-loop-patterns.md
+31
docs-site/docs/guides/mcp-and-tool-loop-patterns.md
···
1
+
# MCP and tool-loop patterns (abstract)
2
+
3
+
!!! note "Conceptual only"
4
+
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.
5
+
6
+
## Tool loop (functions / tools)
7
+
8
+
1. Define tools with **names, descriptions, and JSON Schema** (or equivalent) for arguments.
9
+
2. Send user + conversation + tool definitions to the model.
10
+
3. If the model returns a **tool call**, validate arguments, **execute** on the host, append a **tool_result** message (or provider-specific equivalent).
11
+
4. Repeat until the model finishes without further tool calls or a cap is hit.
12
+
13
+
In this reconstruction, much of that orchestration lives in `query.ts` and adjacent helpers, while tool implementations live under `tools/*` and `services/tools/`.
14
+
15
+
## MCP (Model Context Protocol)
16
+
17
+
**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.
18
+
19
+
For **your** project:
20
+
21
+
- Start from [MCP documentation](https://modelcontextprotocol.io) and official SDKs.
22
+
- Implement **one** small MCP server (e.g. filesystem or git) before designing a full IDE-quality integration.
23
+
24
+
## Parallel: skills and plugins
25
+
26
+
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.
27
+
28
+
## See also
29
+
30
+
- [Building an agentic CLI overview](building-an-agentic-cli-overview.md)
31
+
- [Official: MCP](https://code.claude.com/docs/en/mcp)
+12
-9
docs-site/docs/index.md
+12
-9
docs-site/docs/index.md
···
15
15
16
16
## How to use this site
17
17
18
-
| Section | Purpose |
19
-
| ------------------------------------------- | -------------------------------------------------------------------------------------- |
20
-
| [Installation](installation.md) | Build **this documentation** locally; install the **real** Claude Code from Anthropic. |
21
-
| [Reproducibility](reproducibility.md) | Why you **cannot** rebuild the shipping npm package from this tree alone. |
22
-
| [Architecture](architecture.md) | High-level components and data flow. |
23
-
| [Workflows](workflows.md) | Interactive REPL, print/headless, swarm, compaction paths. |
24
-
| [Official docs map](official-docs-map.md) | Every indexed doc page ↔ `src/` entry points. |
25
-
| [Reference](reference/cli-entry.md) | Deeper dives per subsystem. |
26
-
| [Appendix](appendix/directory-structure.md) | Directory layout, tool packages, environment variables. |
18
+
| Section | Purpose |
19
+
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
20
+
| [Installation](installation.md) | Build **this documentation** locally; install the **real** Claude Code from Anthropic. |
21
+
| [Reproducibility](reproducibility.md) | Why you **cannot** rebuild the shipping npm package from this tree alone. |
22
+
| [System design](system-design/layers.md) | Layers, state/data flow, security and trust model. |
23
+
| [Architecture](architecture.md) | Overview diagram and links into system design + reference. |
24
+
| [Workflows](workflows.md) | Interactive REPL, print/headless, swarm, compaction paths. |
25
+
| [Developer hub](developer/index.md) | Working on docs, navigating `src/`, Bun feature flags. |
26
+
| [Guides](guides/building-an-agentic-cli-overview.md) | **Greenfield** agentic CLI and docs/CI patterns—not cloning this leak. |
27
+
| [Official docs map](official-docs-map.md) | Every indexed doc page ↔ `src/` entry points. |
28
+
| [Reference](reference/cli-entry.md) | Deeper dives per subsystem. |
29
+
| [Appendix](appendix/directory-structure.md) | Directory layout, tool packages, environment variables, [glossary](appendix/glossary.md). |
27
30
28
31
## Repository
29
32
+68
docs-site/docs/system-design/layers.md
+68
docs-site/docs/system-design/layers.md
···
1
+
# Architectural layers
2
+
3
+
!!! warning "Recovered proprietary source"
4
+
Descriptions are for **study** of the `src/` mirror only. This is not an open-source distribution of Claude Code.
5
+
6
+
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).
7
+
8
+
## Layer stack (conceptual)
9
+
10
+
| Layer | Responsibility | Primary `src/` locations |
11
+
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
12
+
| **CLI shell** | argv parsing, global flags, subcommands, `preAction` startup | `main.tsx`, `commands/`, `cli/handlers/` |
13
+
| **Session host** | Interactive TUI vs structured print/SDK transport | `replLauncher.tsx`, `screens/REPL.tsx`, `cli/print.ts`, `cli/structuredIO.ts` |
14
+
| **Query core** | Turn loop, streaming, tool round-trips, context assembly | `query.ts`, `QueryEngine.ts`, `utils/processUserInput/` |
15
+
| **Transport** | Anthropic (and provider) HTTP/streaming | `services/api/` |
16
+
| **Tooling** | Registry, execution, hooks | `tools.ts`, `Tool.ts`, `tools/*`, `services/tools/` |
17
+
| **Integrations** | MCP, LSP, OAuth, IDE bridge | `services/mcp/`, `services/lsp/`, `services/oauth/`, `bridge/` |
18
+
| **Policy & persistence** | Settings, compaction, session storage, telemetry | `utils/settings/`, `services/compact/`, `utils/sessionStorage.ts`, `services/analytics/` |
19
+
20
+
## Dependency direction
21
+
22
+
```mermaid
23
+
flowchart TB
24
+
subgraph presentation [Presentation]
25
+
Main[main.tsx]
26
+
REPL[REPL.tsx]
27
+
Print[cli/print.ts]
28
+
end
29
+
subgraph domain [Domain_core]
30
+
Query[query.ts]
31
+
QE[QueryEngine.ts]
32
+
end
33
+
subgraph ports [Ports]
34
+
API[services/api]
35
+
Tools[tools plus services/tools]
36
+
MCP[services/mcp]
37
+
end
38
+
subgraph infra [Infrastructure]
39
+
Settings[utils/settings]
40
+
Compact[services/compact]
41
+
Store[sessionStorage]
42
+
end
43
+
Main --> REPL
44
+
Main --> Print
45
+
REPL --> Query
46
+
Print --> QE
47
+
Query --> API
48
+
Query --> Tools
49
+
QE --> API
50
+
QE --> Tools
51
+
Tools --> MCP
52
+
Query --> Compact
53
+
QE --> Compact
54
+
Query --> Settings
55
+
Main --> Settings
56
+
```
57
+
58
+
**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.
59
+
60
+
## Feature gates
61
+
62
+
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).
63
+
64
+
## See also
65
+
66
+
- [State and data flow](state-and-data-flow.md)
67
+
- [Security and trust model](security-trust-model.md)
68
+
- [Architecture overview](../architecture.md)
+60
docs-site/docs/system-design/security-trust-model.md
+60
docs-site/docs/system-design/security-trust-model.md
···
1
+
# Security and trust model
2
+
3
+
!!! warning "Recovered proprietary source"
4
+
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.
5
+
6
+
## Trust and workspace
7
+
8
+
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.
9
+
10
+
## Permission modes
11
+
12
+
`utils/permissions/` defines modes (manual approval, auto with classifiers, plan-only variants, etc.). `permissionSetup.ts` and related modules:
13
+
14
+
- Parse CLI flags (`--permission-mode`, internal aliases).
15
+
- Strip or gate “dangerous” capabilities when using auto mode.
16
+
- Feed **always-allow** tool lists into `toolPermissionContext`.
17
+
18
+
User-facing reference: [Permission modes](https://code.claude.com/docs/en/permission-modes).
19
+
20
+
## Bash and sandboxing
21
+
22
+
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.
23
+
24
+
## MCP and enterprise policy
25
+
26
+
- **Config** — `services/mcp/config.ts` parses MCP server lists, env expansion, deduplication, and enterprise allowlists.
27
+
- **Channels** — `services/mcp/channelAllowlist.ts` and related modules gate inbound push notifications.
28
+
29
+
Official: [MCP](https://code.claude.com/docs/en/mcp), [Channels](https://code.claude.com/docs/en/channels).
30
+
31
+
## Hooks
32
+
33
+
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.
34
+
35
+
Official: [Hooks](https://code.claude.com/docs/en/hooks).
36
+
37
+
## Trust check order (conceptual)
38
+
39
+
```mermaid
40
+
flowchart TD
41
+
start[Process_start]
42
+
config[Load_safe_config_order]
43
+
trust[Workspace_trust]
44
+
perms[Permission_mode_setup]
45
+
hooks[Session_hooks]
46
+
tools[Tool_execution]
47
+
start --> config
48
+
config --> trust
49
+
trust --> perms
50
+
perms --> hooks
51
+
hooks --> tools
52
+
```
53
+
54
+
Exact ordering evolves by version; correlate with `main.tsx` `preAction` and `entrypoints/init` when reading the mirror.
55
+
56
+
## See also
57
+
58
+
- [Permissions reference](../reference/permissions.md)
59
+
- [MCP reference](../reference/mcp.md)
60
+
- [Reproducibility and limits](../reproducibility.md)
+50
docs-site/docs/system-design/state-and-data-flow.md
+50
docs-site/docs/system-design/state-and-data-flow.md
···
1
+
# State and data flow
2
+
3
+
!!! warning "Recovered proprietary source"
4
+
For authoritative product behavior, use [official Claude Code docs](https://code.claude.com/docs/en/overview).
5
+
6
+
## End-to-end message path (interactive)
7
+
8
+
1. **Input** — User text, slash commands, teammate notifications, or task items reach `screens/REPL.tsx`.
9
+
2. **Queue** — `utils/queueProcessor.ts` serializes or batches commands and calls `executeInput`.
10
+
3. **Query** — `query.ts` `queryLoop` streams the model, surfaces `tool_use` blocks, and applies permission checks using `toolPermissionContext` from app state.
11
+
4. **Execution** — `services/tools/` (e.g. `StreamingToolExecutor`, `toolExecution.ts`) dispatches to modules under `tools/*` or MCP-backed tools.
12
+
5. **Persistence** — Transcript updates, session metadata, and compaction boundaries flow through `utils/sessionStorage.ts`, conversation recovery helpers, and related hooks.
13
+
14
+
## State ownership
15
+
16
+
| Concern | Typical modules |
17
+
| ----------------------- | ------------------------------------------------------------------------------------------ |
18
+
| **Global app state** | `state/` (providers, stores such as `AppStateStore.ts`) |
19
+
| **Context / stats** | `context/` |
20
+
| **Messages** | `utils/messages.ts`, message types under `types/message` (and generated types) |
21
+
| **Permissions** | `utils/permissions/`, fields on tool permission context updated from CLI and REPL |
22
+
| **File / edit history** | Wired through process-user-input and tool hooks (see compaction and attribution utilities) |
23
+
24
+
## Simplified sequence (one turn)
25
+
26
+
```mermaid
27
+
sequenceDiagram
28
+
participant UI as REPL_or_print
29
+
participant Q as queryLoop
30
+
participant API as services_api
31
+
participant Exec as tool_executor
32
+
participant Store as session_storage
33
+
UI->>Q: user_or_control_messages
34
+
Q->>API: stream_completion
35
+
API-->>Q: assistant_tool_use
36
+
Q->>Exec: run_tool
37
+
Exec-->>Q: tool_result
38
+
Q->>Store: persist_transcript_updates
39
+
Q-->>UI: render_updates
40
+
```
41
+
42
+
## Headless differences
43
+
44
+
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.
45
+
46
+
## See also
47
+
48
+
- [Workflows](../workflows.md)
49
+
- [Query loop and streaming](../reference/query-engine.md)
50
+
- [Compaction](../reference/compaction.md)
+6
docs-site/docs/workflows.md
+6
docs-site/docs/workflows.md
+14
docs-site/mkdocs.yml
+14
docs-site/mkdocs.yml
···
52
52
- Getting started:
53
53
- installation.md
54
54
- reproducibility.md
55
+
- System design:
56
+
- system-design/layers.md
57
+
- system-design/state-and-data-flow.md
58
+
- system-design/security-trust-model.md
55
59
- Architecture:
56
60
- architecture.md
57
61
- workflows.md
62
+
- Developer:
63
+
- developer/index.md
64
+
- developer/editing-documentation.md
65
+
- developer/navigating-the-source.md
66
+
- developer/bun-bundle-and-feature-flags.md
67
+
- Guides:
68
+
- guides/building-an-agentic-cli-overview.md
69
+
- guides/mcp-and-tool-loop-patterns.md
70
+
- guides/documentation-and-ci-for-docs.md
58
71
- Official docs map: official-docs-map.md
59
72
- Reference:
60
73
- reference/cli-entry.md
···
76
89
- appendix/directory-structure.md
77
90
- appendix/tool-packages.md
78
91
- appendix/environment-variables.md
92
+
- appendix/glossary.md
79
93
80
94
plugins:
81
95
- search
+2
docs/README.md
+2
docs/README.md
···
6
6
- Local preview: `cd docs-site && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && mkdocs serve`
7
7
8
8
The file **`directory-structure.md`** in this folder remains a quick `src/` layout reference duplicated in the site under **Appendix → Directory structure**.
9
+
10
+
The published site also includes **System design**, **Developer**, **Guides** (greenfield agent CLI + docs CI), and **Glossary**; see navigation in `docs-site/mkdocs.yml`.