Study Manual

Claude CLI Source Handbook

A local textbook-style reading guide for the downloaded Claude CLI source mirror. The goal is not to run it, but to understand how the client is built: entrypoints, command routing, tools, safety checks, API adapters, MCP, and terminal UI.

Scope This is the client-side CLI application layer: terminal shell, tool bus, UI, API calls, MCP, and session logic. It is not the Anthropic backend or model training stack.

What You Can Learn

  • How a large terminal app uses React + Ink as a product-grade CLI shell.
  • How tool registration and prompt wiring are separated from execution.
  • How dangerous local actions are wrapped in layered permission checks.
  • How a client talks to model APIs, OAuth flows, and MCP servers.
  • How session state, history, compacting, and mode switching are organized.

Project Map

  • source/main.tsx: main CLI boot path
  • source/commands.ts: slash-command registry
  • source/tools.ts: tool registry
  • source/Tool.ts: shared tool contracts
  • source/tools/BashTool/*: command execution safety
  • source/services/api/*: model/API client layer
  • source/services/mcp/*: MCP auth and transport
  • source/components/* and source/ink/*: terminal UI

Chapters

  1. 00. System Overview
  2. 00A. Conceptual How It Works
  3. 01. Startup Flow
  4. 02. Tools and Permission Layers
  5. 03. API Clients and MCP
  6. 04. Terminal UI and Session State
  7. 05. Recommended Reading Order
  8. 06. Deep Read: main.tsx
  9. 07. Deep Read: BashTool
  10. 08. Trust, History, and Compacting
  11. 09. Study Exercises and Skill Gains
  12. 10. Deep Read: commands.ts
  13. 11. Tool Contracts in Tool.ts
  14. 12. Deep Read: services/api/client.ts
  15. 13. Deep Read: services/mcp/auth.ts
  16. 14. Source Map and Module Index
  17. 15. Deep Read: services/api/claude.ts
  18. 16. Deep Read: AgentTool
  19. 17. Prompt Input and Message UI
  20. 18. Global Permission System
  21. 19. Deep Read: FileReadTool
  22. 20. Deep Read: FileEditTool
  23. 21. Session Memory
  24. 22. Compact Subsystem
  25. 23. Top 20 Files to Study

Goal-Based Tracks

  1. 24. Migrate Ideas to Local Qwen
  2. 25. What To Learn vs. Skip
  3. 26. Build Your Own Agent Shell
  4. 27. Adapting to a Lobster-Like Framework

Reading Strategy

Do not start by reading everything. Start with the boot path, then the tool registry, then one concrete tool such as BashTool, then the API layer, then the MCP layer, and only after that the UI and long-tail services.

Current Judgment

The copied tree looks like a large client application source tree, not a normal buildable open-source repository. It contains a rich CLI shell, command router, tool bus, API client code, MCP support, session logic, and a large terminal UI layer. The most valuable engineering lessons are in system decomposition and safety controls, not in any hidden model magic.