How leeyeel/claude-code-sourcemap works
1. Overall shape
Claude Code is a terminal-first agent runtime, not a web app. The repository centers on a CLI that launches an interactive REPL-style experience, routes slash commands, talks to Anthropic’s Claude service, and renders everything in terminal UI components.
2. Entry points and process boundaries
The main runtime starts from cli.mjs and src/entrypoints/cli.tsx, which boot the interactive terminal app. A separate src/entrypoints/mcp.ts exposes the MCP-side entrypoint, indicating this repo can also run as a Model Context Protocol participant for external tool integrations.
3. Command layer
src/commands.ts and src/commands/* define the user-facing command surface: onboarding, login/logout, config, help, resume, review, bug reporting, logs, doctor, clear/compact, cost, and terminal setup. These commands are the top-level control plane for the user and usually transition into screens or mutate local configuration/session state.
4. Interactive REPL and screens
src/screens/REPL.tsx is the core interactive session surface. Other screens such as onboarding, resume conversation, log list, doctor, and npm prefix configuration are separate UI states used for specific workflow transitions. This is a terminal UI application with screen-based navigation rather than browser-style routing.
5. Conversation and message model
src/messages.ts, src/history.ts, src/query.ts, and the many src/components/messages/* files indicate a structured conversation log. User prompts, assistant reasoning, tool calls, tool results, and command events are all rendered as distinct message types, which is important for understanding the data flow through the UI and the persistence of session history.
6. Tool execution subsystem
src/tools/* is the main agent action layer. It includes filesystem and shell tools (Bash, FileRead, FileWrite, FileEdit, Glob, Grep, ls), notebook tools, memory tools, an MCP tool bridge, and specialized agent/architect/think/sticker-request tools. Each tool has its own prompt and UI wrapper, implying a common tool protocol with tool-specific rendering and result handling.
7. Permissions and trust boundary
Tool use is gated by a dedicated permissions subsystem in src/permissions.ts, src/components/permissions/*, and src/utils/permissions/*. Bash, filesystem, and file-edit/write actions can trigger explicit approval dialogs, with fallback/rejection/error messaging. This is a key architectural boundary: the model proposes actions, but local permission logic controls whether they execute.
8. Claude API and session orchestration
src/services/claude.ts is the primary boundary to Anthropic’s model service. The surrounding hooks and utilities (useCanUseTool, useCancelRequest, useLogMessages, useNotifyAfterTimeout, useSlashCommandTypeahead, etc.) coordinate streaming responses, cancellation, notification, and input behavior while the UI remains reactive to model output and tool events.
9. Authentication and product services
Login and API key verification are handled through OAuth and key-specific flows (src/services/oauth.ts, src/utils/auth.ts, src/hooks/useApiKeyVerification.ts, src/components/ConsoleOAuthFlow.tsx). Additional product integrations include Sentry (src/services/sentry.ts), Statsig feature/experiment state (src/services/statsig.ts, src/services/statsigStorage.ts), and desktop notifications (src/services/notifier.ts).
10. MCP and external tool ecosystem
The repo has explicit MCP support via src/services/mcpClient.ts, src/services/mcpServerApproval.tsx, and the MCP tool/UI pieces. This creates a second integration boundary beyond the local shell/filesystem: external MCP servers can be discovered, approved, and used as first-class tools in the conversation loop.
11. Local state, config, and persistence
User state is spread across config and session helpers in src/utils/config.ts, src/utils/state.ts, src/utils/user.ts, src/utils/log.ts, and history-related code. The app persists conversation context, trust decisions, and runtime settings so that sessions can be resumed and commands like /resume, /clear, and /compact work predictably.
12. UX and rendering layer
src/components/* contains the terminal UI primitives: prompts, selectors, dialogs, diff viewers, structured message renderers, onboarding, cost warnings, updater prompts, and error boundaries. These components are purely presentation and interaction logic; they do not own agent behavior, but they define how tool results, permission requests, and warnings are shown to the user.
13. Operational concerns
The repo includes doctor/diagnostic flows, cost tracking, auto-update support, token warnings, and startup logging. These indicate the app is designed to manage a long-running interactive session in the terminal, with guardrails around API usage, installation health, and upgrade prompts.
14. Practical architecture diagram takeaway
The key diagram should show: terminal CLI entrypoint → command/screen controller → conversation/session state → Claude API stream → tool execution subsystem → permission gate → local filesystem/shell/MCP services → rendered message history back into the REPL. Surround that core with auth, config/persistence, telemetry, and onboarding/diagnostics as supporting subsystems.
Main entry points: tools.ts Tools · REPL.tsx REPL screen · commands.ts Command router · claude.ts Claude API
Components 33
Runtime
Terminal entrypoints, screens, commands, and conversation flow.
- CLI bootstrap · Process start for the terminal app.
cli.mjs - CLI app · Boots the interactive terminal experience.
src/entrypoints/cli.tsx - MCP entry · Exposes the MCP-side process boundary.
src/entrypoints/mcp.ts - Command router · Top-level slash commands and workflow actions.
src/commands.ts - REPL screen · Main interactive terminal session surface.
src/screens/REPL.tsx - Resume screen · Restores prior conversations and session state.
src/screens/ResumeConversation.tsx - Log screen · Lists and selects saved logs or sessions.
src/screens/LogList.tsx - Doctor screen · Runs health checks and setup diagnostics.
src/screens/Doctor.tsx
Tools
Agent actions and external execution surfaces.
- Tools · Shared tool protocol and tool set wiring.
src/tools.ts - Bash · Runs shell commands in the local terminal environment.
src/tools/BashTool/BashTool.tsx - File tools · Read, write, and edit files in the workspace.
src/tools/FileReadTool/FileReadTool.tsx - Search tools · Glob, grep, and directory listing actions.
src/tools/GlobTool/GlobTool.tsx - MCP tool · Bridges the agent to MCP-provided capabilities.
src/tools/MCPTool/MCPTool.tsx - Memory tools · Reads and writes persistent memory context.
src/tools/MemoryReadTool/MemoryReadTool.tsx - Notebook tools · Reads and edits notebook-style artifacts.
src/tools/NotebookReadTool/NotebookReadTool.tsx - Agent extras · Thinking, architecting, stickers, and agent helpers.
src/tools/ThinkTool/ThinkTool.tsx
Services
Model, auth, telemetry, updates, and external integrations.
- Claude API · Primary boundary to Anthropic streaming responses.
src/services/claude.ts - Auth · OAuth and key verification flows.
src/services/oauth.ts - MCP client · Discovers and talks to external MCP servers.
src/services/mcpClient.ts - Notifier · Desktop notifications and alerts.
src/services/notifier.ts - Statsig · Experiment and feature state management.
src/services/statsig.ts - Sentry · Error reporting and monitoring.
src/services/sentry.ts - Auto-update · Update checks and upgrade prompts.
src/utils/autoUpdater.ts
State
Conversation history, config, persistence, and permissions.
- Messages · Structured user, assistant, tool, and command events.
src/messages.ts - History · Conversation history and replayable session records.
src/history.ts - Query flow · Tracks current request and interaction state.
src/query.ts - Permissions · Approval and trust logic for tool execution.
src/permissions.ts - Config · User configuration and persisted app settings.
src/utils/config.ts - State store · Persistent runtime and user state helpers.
src/utils/state.ts
UI
Terminal rendering, dialogs, message views, and prompts.
- Messages UI · Renders assistant, user, and tool messages.
src/components/messages/AssistantTextMessage.tsx - Permission UI · Approval prompts and trust dialogs for risky actions.
src/components/permissions/PermissionRequest.tsx - Prompt input · Terminal prompt, selectors, and text input components.
src/components/PromptInput.tsx - Support UI · Onboarding, config, cost, logs, errors, and updater screens.
src/components/Onboarding.tsx
Connections 36
- CLI bootstrap → CLI app: starts · Node/launcher hands off to the TypeScript CLI app.
- CLI app → Command router: routes · Interactive commands are dispatched from the terminal app.
- CLI app → REPL screen: opens · Starts the main REPL-style session surface.
- Command router → Resume screen: navigates · Resume-related commands open the resume workflow.
- Command router → Log screen: navigates · Log and session listing commands open the log browser.
- Command router → Doctor screen: navigates · Doctor command opens diagnostics.
- REPL screen → Messages: renders · Session UI is driven by structured messages.
- REPL screen → Query flow: updates · Tracks the current prompt and interaction state.
- REPL screen → Claude API: streams · Sends prompts and receives model output.
- Claude API → Tools: requests tools · Model output can trigger tool execution.
- Tools → Bash: includes · Shell execution is a primary tool.
- Tools → File tools: includes · File read/write/edit capabilities.
- Tools → Search tools: includes · Search and listing helpers.
- Tools → MCP tool: includes · External MCP tool bridge.
- Tools → Memory tools: includes · Persistent memory access.
- Tools → Notebook tools: includes · Notebook-specific editing tools.
- Tools → Agent extras: includes · Thinking and agent helper tools.
- Tools → Permissions: gated by · Sensitive actions require approval.
- Permissions → Permission UI: prompts · Shows approval dialogs and trust requests.
- Permissions → Bash: guards · Shell actions can require explicit consent.
- Permissions → File tools: guards · File edits and writes can require approval.
- Permissions → MCP client: guards · External MCP use is mediated by approval.
- History → Messages: stores · Persists conversation and tool event history.
- State store → Config: persists · Holds runtime and user settings.
- State store → History: persists · Supports resume and session continuity.
- Auth → Config: writes · Auth state and credentials flow into local config.
- REPL screen → Messages UI: renders · Conversation content is shown through message components.
- REPL screen → Prompt input: accepts input · Terminal text entry and command selection happen here.
- REPL screen → Support UI: shows · Onboarding, config, cost, and other support views.
- Claude API → Notifier: alerts · Timeouts and completion states can notify the user.
- Claude API → Statsig: tracks · Feature and experiment state influences runtime behavior.
- Claude API → Sentry: reports · Errors and telemetry flow to monitoring.
- CLI app → Auto-update: checks · Startup can trigger update checks.
- MCP entry → MCP client: hosts · Separate process boundary for MCP participation.
- Command router → Auth: authenticates · Login and key verification commands use auth services.
- Command router → Config: modifies · Config-related commands update local settings.