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

add developer docs

Browse Source
This commit is contained in:
Osman Mehmood
2026-03-31 16:04:03 +05:00
parent 35408dd369
commit 51fa1eeca5
17 changed files with 468 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -121,7 +121,7 @@ Execution paths converge on shared **state** (`state/`, `bootstrap/`), **permiss
## Documentation (GitHub Pages)
Full internals documentation (architecture, workflows, official-docs cross-reference, subsystem reference, appendices) is built with **MkDocs Material** from [`docs-site/`](docs-site/).
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).
- **Live site:** [https://mehmoodosman.github.io/claude-code-source-code/](https://mehmoodosman.github.io/claude-code-source-code/)
- **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 Normal file
View File

@@ -0,0 +1,20 @@
# 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/`. |

55
docs-site/docs/architecture.md
View File

@@ -1,4 +1,4 @@
# Architecture
# Architecture overview
!!! warning "Recovered source"
Paths refer to `src/` in this repository. Line-level accuracy is best-effort from the source map reconstruction.
@@ -37,43 +37,21 @@ flowchart LR
qe --> compact
```
## Entry and startup
## System design (deeper dives)
`src/main.tsx` is the **Commander**-based CLI. Before the command handler runs, module evaluation triggers:
| 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) |
- Startup profiling checkpoints (`utils/startupProfiler.ts`)
- MDM raw reads in parallel (`utils/settings/mdm/rawRead.ts`)
- macOS keychain prefetch (`utils/secureStorage/keychainPrefetch.ts`)
## Short orientation
The `preAction` hook loads trust, settings, telemetry gates, MCP prefetch, policy limits, and related startup work before interactive or print mode begins.
## Interactive mode
- `replLauncher.tsx` mounts the Ink/React app.
- `screens/REPL.tsx` owns the main session UI, input queue, model turns, tool execution UI, teammate hooks, voice (when compiled in), and scheduled-task integration.
- `utils/queueProcessor.ts` drains slash commands, bash-mode lines, and batched prompts into `executeInput`.
## Headless / print / SDK-style I/O
- `cli/print.ts` implements structured stdin/stdout loops (`runHeadlessStreaming`, NDJSON-style control).
- `QueryEngine.ts` supports non-REPL paths where messages are submitted programmatically and tool permission context is updated without full UI.
## Tools and MCP
- `tools.ts` aggregates built-in tools (filtered by permission context) and merges MCP-derived tools.
- `services/mcp/` implements config parsing, transports, OAuth, channel permissions, and the in-process MCP client used by `MCPConnectionManager` in the UI.
## Compaction and memory
- `services/compact/` implements context window management aligned with user-facing [context window](https://code.claude.com/docs/en/context-window) and [costs](https://code.claude.com/docs/en/costs) documentation.
## Multi-agent (swarm / teammates)
- `utils/swarm/` contains backends (tmux, iTerm, in-process), spawn utilities, permission sync, and `inProcessRunner.ts` teammate loop.
## IDE integration
- `bridge/` plus hooks such as `hooks/useDiffInIDE.ts` connect to VS Code / JetBrains surfaces described in official [VS Code](https://code.claude.com/docs/en/vs-code) and [JetBrains](https://code.claude.com/docs/en/jetbrains) docs.
- **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)
@@ -90,4 +68,9 @@ The `preAction` hook loads trust, settings, telemetry gates, MCP prefetch, polic
| `services/compact/` | Compaction pipeline |
| `utils/sessionStart.ts` | Session / setup hooks |
See also [Workflows](workflows.md) and the [official docs map](official-docs-map.md).
## 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).

26
docs-site/docs/developer/bun-bundle-and-feature-flags.md Normal file
View File

@@ -0,0 +1,26 @@
# 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)

29
docs-site/docs/developer/editing-documentation.md Normal file
View File

@@ -0,0 +1,29 @@
# 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).

25
docs-site/docs/developer/index.md Normal file
View File

@@ -0,0 +1,25 @@
# 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)

37
docs-site/docs/developer/navigating-the-source.md Normal file
View File

@@ -0,0 +1,37 @@
# 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.).

39
docs-site/docs/guides/building-an-agentic-cli-overview.md Normal file
View File

@@ -0,0 +1,39 @@
# 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.

29
docs-site/docs/guides/documentation-and-ci-for-docs.md Normal file
View File

@@ -0,0 +1,29 @@
# 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)

31
docs-site/docs/guides/mcp-and-tool-loop-patterns.md Normal file
View File

@@ -0,0 +1,31 @@
# 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)

9
docs-site/docs/index.md
View File

@@ -16,14 +16,17 @@ The recovered codebase implements primarily the **terminal CLI** surface, plus s
## How to use this site
| Section | Purpose |
| ------------------------------------------- | -------------------------------------------------------------------------------------- |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [Installation](installation.md) | Build **this documentation** locally; install the **real** Claude Code from Anthropic. |
| [Reproducibility](reproducibility.md) | Why you **cannot** rebuild the shipping npm package from this tree alone. |
| [Architecture](architecture.md) | High-level components and data flow. |
| [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. |
| [Appendix](appendix/directory-structure.md) | Directory layout, tool packages, environment variables, [glossary](appendix/glossary.md). |
## Repository

68
docs-site/docs/system-design/layers.md Normal file
View File

@@ -0,0 +1,68 @@
# 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)

60
docs-site/docs/system-design/security-trust-model.md Normal file
View File

@@ -0,0 +1,60 @@
# 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)

50
docs-site/docs/system-design/state-and-data-flow.md Normal file
View File

@@ -0,0 +1,50 @@
# 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)

6
docs-site/docs/workflows.md
View File

@@ -75,3 +75,9 @@ sequenceDiagram
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)

14
docs-site/mkdocs.yml
View File

@@ -52,9 +52,22 @@ nav:
- 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
@@ -76,6 +89,7 @@ nav:
- appendix/directory-structure.md
- appendix/tool-packages.md
- appendix/environment-variables.md
- appendix/glossary.md
plugins:
- search

2
docs/README.md
View File

@@ -6,3 +6,5 @@ The **MkDocs site** (for GitHub Pages) lives in **`docs-site/`**.
- 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`.