From 51fa1eeca502a303eabad3f9fed7086020a81ca0 Mon Sep 17 00:00:00 2001 From: Osman Mehmood <88900308+mehmoodosman@users.noreply.github.com> Date: Tue, 31 Mar 2026 16:04:03 +0500 Subject: [PATCH] add developer docs --- README.md | 2 +- docs-site/docs/appendix/glossary.md | 20 ++++++ docs-site/docs/architecture.md | 55 ++++++--------- .../developer/bun-bundle-and-feature-flags.md | 26 +++++++ .../docs/developer/editing-documentation.md | 29 ++++++++ docs-site/docs/developer/index.md | 25 +++++++ .../docs/developer/navigating-the-source.md | 37 ++++++++++ .../building-an-agentic-cli-overview.md | 39 +++++++++++ .../guides/documentation-and-ci-for-docs.md | 29 ++++++++ .../docs/guides/mcp-and-tool-loop-patterns.md | 31 +++++++++ docs-site/docs/index.md | 21 +++--- docs-site/docs/system-design/layers.md | 68 +++++++++++++++++++ .../system-design/security-trust-model.md | 60 ++++++++++++++++ .../docs/system-design/state-and-data-flow.md | 50 ++++++++++++++ docs-site/docs/workflows.md | 6 ++ docs-site/mkdocs.yml | 14 ++++ docs/README.md | 2 + 17 files changed, 468 insertions(+), 46 deletions(-) create mode 100644 docs-site/docs/appendix/glossary.md create mode 100644 docs-site/docs/developer/bun-bundle-and-feature-flags.md create mode 100644 docs-site/docs/developer/editing-documentation.md create mode 100644 docs-site/docs/developer/index.md create mode 100644 docs-site/docs/developer/navigating-the-source.md create mode 100644 docs-site/docs/guides/building-an-agentic-cli-overview.md create mode 100644 docs-site/docs/guides/documentation-and-ci-for-docs.md create mode 100644 docs-site/docs/guides/mcp-and-tool-loop-patterns.md create mode 100644 docs-site/docs/system-design/layers.md create mode 100644 docs-site/docs/system-design/security-trust-model.md create mode 100644 docs-site/docs/system-design/state-and-data-flow.md diff --git a/README.md b/README.md index eb517a7..52f6111 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/docs-site/docs/appendix/glossary.md b/docs-site/docs/appendix/glossary.md new file mode 100644 index 0000000..9eb49e7 --- /dev/null +++ b/docs-site/docs/appendix/glossary.md @@ -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/`. | diff --git a/docs-site/docs/architecture.md b/docs-site/docs/architecture.md index 905f2ce..3fc389c 100644 --- a/docs-site/docs/architecture.md +++ b/docs-site/docs/architecture.md @@ -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). diff --git a/docs-site/docs/developer/bun-bundle-and-feature-flags.md b/docs-site/docs/developer/bun-bundle-and-feature-flags.md new file mode 100644 index 0000000..8579d14 --- /dev/null +++ b/docs-site/docs/developer/bun-bundle-and-feature-flags.md @@ -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) diff --git a/docs-site/docs/developer/editing-documentation.md b/docs-site/docs/developer/editing-documentation.md new file mode 100644 index 0000000..50baf7a --- /dev/null +++ b/docs-site/docs/developer/editing-documentation.md @@ -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). diff --git a/docs-site/docs/developer/index.md b/docs-site/docs/developer/index.md new file mode 100644 index 0000000..ff3f763 --- /dev/null +++ b/docs-site/docs/developer/index.md @@ -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) diff --git a/docs-site/docs/developer/navigating-the-source.md b/docs-site/docs/developer/navigating-the-source.md new file mode 100644 index 0000000..1d91aba --- /dev/null +++ b/docs-site/docs/developer/navigating-the-source.md @@ -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.). diff --git a/docs-site/docs/guides/building-an-agentic-cli-overview.md b/docs-site/docs/guides/building-an-agentic-cli-overview.md new file mode 100644 index 0000000..0430e86 --- /dev/null +++ b/docs-site/docs/guides/building-an-agentic-cli-overview.md @@ -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. diff --git a/docs-site/docs/guides/documentation-and-ci-for-docs.md b/docs-site/docs/guides/documentation-and-ci-for-docs.md new file mode 100644 index 0000000..b418656 --- /dev/null +++ b/docs-site/docs/guides/documentation-and-ci-for-docs.md @@ -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) diff --git a/docs-site/docs/guides/mcp-and-tool-loop-patterns.md b/docs-site/docs/guides/mcp-and-tool-loop-patterns.md new file mode 100644 index 0000000..c5110be --- /dev/null +++ b/docs-site/docs/guides/mcp-and-tool-loop-patterns.md @@ -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) diff --git a/docs-site/docs/index.md b/docs-site/docs/index.md index 26645cf..a5500fa 100644 --- a/docs-site/docs/index.md +++ b/docs-site/docs/index.md @@ -15,15 +15,18 @@ 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. | -| [Workflows](workflows.md) | Interactive REPL, print/headless, swarm, compaction paths. | -| [Official docs map](official-docs-map.md) | Every indexed doc page ↔ `src/` entry points. | -| [Reference](reference/cli-entry.md) | Deeper dives per subsystem. | -| [Appendix](appendix/directory-structure.md) | Directory layout, tool packages, environment variables. | +| 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 diff --git a/docs-site/docs/system-design/layers.md b/docs-site/docs/system-design/layers.md new file mode 100644 index 0000000..9cc9ffe --- /dev/null +++ b/docs-site/docs/system-design/layers.md @@ -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) diff --git a/docs-site/docs/system-design/security-trust-model.md b/docs-site/docs/system-design/security-trust-model.md new file mode 100644 index 0000000..3e4d196 --- /dev/null +++ b/docs-site/docs/system-design/security-trust-model.md @@ -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) diff --git a/docs-site/docs/system-design/state-and-data-flow.md b/docs-site/docs/system-design/state-and-data-flow.md new file mode 100644 index 0000000..e75873a --- /dev/null +++ b/docs-site/docs/system-design/state-and-data-flow.md @@ -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) diff --git a/docs-site/docs/workflows.md b/docs-site/docs/workflows.md index 057886d..86cfd04 100644 --- a/docs-site/docs/workflows.md +++ b/docs-site/docs/workflows.md @@ -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) diff --git a/docs-site/mkdocs.yml b/docs-site/mkdocs.yml index 84ffeba..0c78a25 100644 --- a/docs-site/mkdocs.yml +++ b/docs-site/mkdocs.yml @@ -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 diff --git a/docs/README.md b/docs/README.md index 95a2ef8..59f3785 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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`.