How donutshinobu/claude-code-fork works
1. Overall shape
This is a TypeScript/Bun CLI application built around a terminal React UI. The repo is organized as a layered agent runtime: user input and slash commands enter at the UI/CLI layer, are translated into actions, sent through a query/orchestration engine, and then fanned out to tools, services, or remote bridges before results are rendered back into the terminal.
2. Entry and startup boundary
src/main.tsx, src/entrypoints/, src/setup.ts, and src/bootstrap/ are the boot path. Startup work includes config/bootstrap loading, session restoration, and prefetch-style initialization for settings/auth-related state. From there the app enters the main Ink-based screen flow (src/screens/, src/components/App.tsx) rather than a traditional HTTP server lifecycle.
3. Terminal UI and input pipeline
The user-facing shell is built with React + Ink in src/ink/ and src/components/. Input is handled through keybinding and prompt subsystems (src/keybindings/, src/components/PromptInput/, src/hooks/use*Input*). These feed either slash commands or conversational prompts into the core processing pipeline, while stateful UI concerns live in src/state/ and src/context/.
4. Command system
src/commands.ts and src/commands/ implement the slash-command surface area. Commands are a separate control plane from model chat: they manage sessions, config, auth, plugins, diagnostics, memory, review, diff, remote setup, and similar operations. Many commands are UI-driven React screens, but they ultimately mutate shared app state or invoke backend services.
5. Core query/orchestration engine
src/QueryEngine.ts is the central execution loop for model interactions. It is responsible for streaming responses, tool-call orchestration, retry/continuation behavior, and token/cost accounting (src/cost-tracker.ts, src/services/tokenEstimation.ts). Conceptually this is the main data plane: prompt/context in, model output and tool calls out, with iterative feedback from tool results back into the conversation.
6. Tool boundary
src/Tool.ts plus src/tools/ define the tool contract and individual tool implementations. Each tool is a self-contained module with schema, permission expectations, and UI/progress behavior. The main categories are filesystem/code tools, shell tools, web tools, LSP/MCP integrations, agent spawning, task/team tools, worktree/plan-mode controls, scheduling, and messaging. Tool output is surfaced as structured messages in the conversation UI.
7. Permission and safety gate
Tool execution is not direct; it is mediated by src/hooks/toolPermission/ and the permission-related utilities in src/utils/permissions/. This layer decides whether a tool call is auto-approved, blocked, or presented to the user for confirmation. It also encodes policy modes such as plan/bypass/auto-style behavior, plus shell/file safety rules and denial tracking.
8. Services layer and external integrations
src/services/ is the integration layer for external systems and long-lived capabilities. This includes Anthropic API access (api/), OAuth (oauth/), telemetry/analytics (analytics/, telemetry utilities), LSP server management (lsp/), MCP connection management (mcp/), plugin installation/loading (plugins/), remote-managed settings and policy limits, compacting/context reduction, memory extraction, and voice. These services are used by the query engine, commands, and tools rather than directly by UI components.
9. Session, history, and persistence
Conversation/session continuity is spread across src/history.ts, src/assistant/sessionHistory.ts, src/utils/session*, src/utils/conversationRecovery.ts, and the state store in src/state/. Persistent memory is handled separately in src/memdir/ and memory-related services/hooks. This creates a distinction between transient chat/session state and longer-lived user/team memory that is scanned, synced, and compacted over time.
10. Remote, bridge, and distributed execution
src/bridge/, src/remote/, src/server/, and src/upstreamproxy/ form the distributed-control boundary. The bridge layer connects IDE clients and other frontends to the CLI; remote session code manages remote execution/session transport; server/direct-connect code exposes session entry points; the upstream proxy layer handles network relay behavior. These subsystems let the same core agent runtime be driven from local terminal, IDE, or remote session contexts.
11. Multi-agent and task orchestration
The repo has a clear second orchestration plane beyond single-turn chat: src/coordinator/, src/tasks/, src/tools/AgentTool/, and src/utils/swarm/ support spawning, coordinating, and monitoring multiple agents/tasks. The UI has dedicated task screens and components, while permissions and message routing are adapted for leader/worker or teammate-style workflows. This is a major architectural boundary because these flows are stateful and concurrent, not just linear prompt/response.
12. Extensibility: plugins, skills, and MCP
Extensibility is a first-class subsystem. Plugins (src/plugins/, src/utils/plugins/) extend commands, tools, hooks, and output styles. Skills (src/skills/, src/tools/SkillTool/) package reusable workflows and prompts. MCP integration (src/services/mcp/, src/tools/MCPTool/) adds external tool servers as a dynamic capability surface. Together these form the “capability expansion” layer above the built-in runtime.
13. Context shaping and compaction
Several services shape what the model sees before each turn: src/context.ts, src/query/, src/services/compact/, src/services/extractMemories/, src/utils/context*, and the session/memory systems. The flow is: collect local repo/session/tool context, trim or summarize when needed, inject system prompts and memory, then feed the reduced context into the query engine. This is central to diagramming because the model never consumes raw app state directly.
14. Cross-cutting infrastructure
The repo contains a large supporting utility layer in src/utils/ plus native helpers in src/native-ts/. These cover process/shell execution, filesystem and git operations, sandboxing, terminal rendering, config and settings, auth/keychain, telemetry, JSON/schema validation, and platform-specific behavior. Architecturally these are the lower-level building blocks reused by commands, tools, services, and UI, rather than independent subsystems.
15. Main external dependencies and runtime assumptions
The important external boundaries are Anthropic’s API, MCP servers, LSP servers, OAuth providers, git/shell subprocesses, and optional IDE/remote clients. The runtime is Bun, with React/Ink for terminal rendering and Zod-style schema validation in many command/tool boundaries. If drawing the diagram, the key separation is: terminal/UI on one side, orchestration and policy in the middle, and model/API/tool/remote services on the other.
Main entry points: QueryEngine.ts Query Engine · BashTool.tsx Core Tools · App.tsx Prompt UI · processUserInput.ts Input Parser
Components 23
Runtime & UI
Bootstrap, terminal UI, input, and shared app state.
- Startup · Boot path that loads config and enters the terminal app.
src/main.tsx - Bootstrap · Startup initialization and persisted state setup.
src/bootstrap/state.ts - Ink UI · Ink/React terminal shell and screen composition.
src/ink/components/App.tsx - Prompt UI · Main conversation shell, prompt input, and UI plumbing.
src/components/App.tsx - Keybinds · Keyboard shortcuts, binding resolution, and user input mapping.
src/keybindings/defaultBindings.ts - App State · Shared client state for session, UI, and runtime coordination.
src/state/AppStateStore.ts
Orchestration
Core query loop, context shaping, commands, permissions, and session flow.
- Slash Commands · Command registry and command screens for session, config, auth, and diagnostics.
src/commands.ts - Input Parser · Routes text, slash commands, and bash-like inputs into the right execution path.
src/utils/processUserInput/processUserInput.ts - Query Engine · Main model execution loop with streaming, retries, continuation, and tool orchestration.
src/QueryEngine.ts - Context Builder · Builds and trims model context from session, repo, memory, and tool state.
src/context.ts - Permissions · Approves, blocks, or escalates tool use under plan/auto/bypass modes.
src/hooks/toolPermission/PermissionContext.ts - Session History · Conversation continuity, recovery, and historical session state.
src/assistant/sessionHistory.ts
Capabilities
Built-in tools, multi-agent/task workflows, skills, and plugin expansion.
- Tool Contract · Shared tool interface and structured tool result surface.
src/Tool.ts - Core Tools · Filesystem, shell, fetch, LSP, MCP, task, and messaging tools.
src/tools/BashTool/BashTool.tsx - Agent Tools · Subagent spawning, agent memory, and built-in agent definitions.
src/tools/AgentTool/AgentTool.tsx - Tasks · Background, shell, agent, and remote task lifecycle management.
src/tasks/LocalAgentTask/LocalAgentTask.tsx - Extensibility · Plugin loading, skills, output styles, and capability expansion.
src/plugins/builtinPlugins.ts
Integrations
External APIs, LSP/MCP/OAuth, telemetry, memory, and persistence services.
- API Client · Anthropic and related backend API access plus retries and usage.
src/services/api/claude.ts - LSP & MCP · Language servers, MCP connections, and dynamic tool servers.
src/services/mcp/MCPConnectionManager.tsx - Memory · Session memory extraction, compaction, and team memory sync.
src/services/SessionMemory/sessionMemory.ts - Telemetry · Event logging, tracing, and usage/diagnostic reporting.
src/services/analytics/index.ts
Remote & Bridge
Remote session transport, IDE bridge, and distributed control surfaces.
- Remote Bridge · Bridge, remote sessions, server entrypoints, and upstream proxying.
src/bridge/bridgeMain.ts - Direct Connect · Server-side session creation and direct-connect session management.
src/server/createDirectConnectSession.ts
Connections 24
- Startup → Bootstrap: initializes · Bootstraps runtime state and startup configuration.
- Bootstrap → Ink UI: enters UI · Hands off to the terminal React screen flow.
- Ink UI → Prompt UI: renders · Composes the main app shell and screens.
- Prompt UI → Keybinds: captures input · Maps keystrokes and shortcuts into actions.
- Keybinds → Input Parser: routes · Converts user input into prompt or command handling.
- Input Parser → Slash Commands: dispatches commands · Sends slash commands to the command control plane.
- Input Parser → Query Engine: sends prompts · Hands conversational turns to the model runtime.
- Prompt UI → App State: reads state · UI consumes shared application state and selectors.
- Query Engine → Context Builder: requests context · Builds model input from conversation, repo, tools, and memory.
- Query Engine → Permissions: gates tools · Tool calls are checked before execution.
- Query Engine → Tool Contract: invokes · Executes tool calls through the shared tool interface.
- Tool Contract → Core Tools: implements · Core built-in tools provide the main capability surface.
- Tool Contract → Agent Tools: implements · Subagent-related tools extend the tool boundary.
- Core Tools → Tasks: spawns work · Tools create and monitor background or agent tasks.
- Query Engine → API Client: calls model API · Streams prompts and responses through the provider client.
- Core Tools → LSP & MCP: uses integrations · LSP and MCP-backed tools rely on external connection managers.
- Context Builder → Memory: hydrates memory · Context assembly pulls in long-lived memory and summaries.
- Slash Commands → Extensibility: extends via · Commands expose plugin and skill management surfaces.
- Extensibility → Core Tools: adds capabilities · Plugins and skills can register or augment tools and behavior.
- Remote Bridge → Direct Connect: connects · Remote control surfaces feed into direct-connect session entrypoints.
- Remote Bridge → Query Engine: drives runtime · Remote and bridge clients can exercise the same agent loop.
- Telemetry → Query Engine: observes · Execution, usage, and tracing wrap the core loop.
- Session History → Context Builder: restores · Recovered session state contributes to turn context.
- App State → Session History: persists · App state tracks the active session and history.