How abhirupkumar/claude-code works
1. Overall shape
- This repo is a monorepo for a Bun/TypeScript AI agent system with three main surfaces:
- the CLI product under src/
- a separate web app under web/
- a standalone MCP source-explorer server under mcp-server/
- The core architecture is the CLI agent loop; the web app and MCP server are adjacent interfaces, not the primary runtime.
2. Primary runtime: CLI + Ink UI
- The CLI entrypoints in src/main.tsx and src/entrypoints/cli.tsx bootstrap configuration, auth, and feature flags, then render a React + Ink terminal UI.
- src/components/ contains the terminal screens, dialogs, and message views; src/screens/ holds full-screen flows like REPL, Doctor, and resume views.
- src/state/, src/context/, and many src/hooks/ files coordinate UI state, session state, keyboard handling, notifications, and live updates.
3. Core agent loop
- The heart of the system is src/QueryEngine.ts, which drives LLM calls, streaming responses, reasoning/tool-use loops, retries, token accounting, and context management.
- User input is normalized through src/utils/processUserInput/ and command handling, then handed into the query pipeline.
- The query layer owns the transition from prompt → model response → tool requests → tool results → next turn.
4. Tool system boundary
- Tools live in src/tools/ and are the main capability boundary of the agent.
- Each tool is a separate module with its own schema, UI, prompt text, and validation logic.
- Major tool groups include file operations, shell execution, search, web access, sub-agents, MCP access, tasks, scheduling, and mode/state changes.
- Tool execution is orchestrated through src/services/tools/, especially the streaming executor and orchestration helpers.
5. Permission and safety layer
- Tool use is gated by src/hooks/toolPermission/ and src/utils/permissions/, which determine whether a tool call is allowed, denied, or needs user approval.
- The UI for these decisions lives in src/components/permissions/.
- This is a major architectural boundary: model intent does not directly equal execution; every sensitive action passes through policy, sandbox, and user confirmation checks.
6. Command system
- Slash commands are registered in src/commands.ts and implemented in src/commands/.
- Commands cover session control, review, memory, config, MCP management, compacting, resuming, desktop/mobile handoff, and diagnostics.
- Conceptually, commands are user-driven control-plane actions, while tools are model-driven action-plane operations.
7. Service layer for external systems
- src/services/ contains the integration layer that supports the agent loop:
- api/ for Anthropic API calls, file/bootstrap flows, and usage/error handling
- oauth/ for authentication
- mcp/ for Model Context Protocol connectivity
- lsp/ for language-server-backed code intelligence
- analytics/ and telemetry for usage and feature experimentation
- plugins/, compact/, extractMemories/, teamMemorySync/, and remoteManagedSettings/ for higher-level platform behaviors
- These services are mostly infrastructure behind the agent, not user-facing UI.
8. Bridge and IDE integration
- src/bridge/ is the bidirectional bridge between the CLI and IDE extensions such as VS Code or JetBrains.
- It handles session lifecycle, messaging, permissions callbacks, JWT/auth utilities, and transport/session management.
- The bridge is a separate communication plane that lets the CLI and editor synchronize prompts, permissions, and task/session state.
9. Remote and server modes
- src/server/web/ implements a browser-accessible terminal/session server with auth, pty handling, session management, user storage, and static frontend assets.
- src/remote/ adds remote session coordination and websocket-based session transport.
- These are distinct from the local CLI: they expose the same underlying session/agent model over networked interfaces.
10. State, persistence, and memory
- Persistent user/session memory is handled by src/memdir/, src/history.ts, src/assistant/, and parts of src/services/SessionMemory/.
- src/tasks/ and src/services/task... logic manage long-running work, background tasks, and task output.
- This layer is where the system preserves continuity across turns, sessions, and remote handoffs.
11. Extensibility model: plugins, skills, MCP, LSP
- src/plugins/ and src/utils/plugins/ form the plugin architecture, including discovery, loading, validation, policy, and marketplace support.
- src/skills/ is the reusable workflow layer; skills are loaded and invoked as higher-level behaviors.
- MCP, LSP, and plugins are separate extension channels: MCP connects to external tools/services, LSP to language tooling, and plugins to packaged product extensions.
12. Web app as a separate product surface
- The web/ directory is a distinct Next.js application with its own API routes, React UI, collaboration features, file viewer, export flows, and settings screens.
- It shares concepts with the CLI—conversations, tools, permissions, sessions—but is architecturally separate and browser-native.
- The web/lib/ layer provides client APIs, collaboration sockets, persistence helpers, search, export formats, and performance tooling.
13. Build-time and runtime boundaries
- The repo uses Bun heavily, and bun:bundle feature flags are used to dead-strip code paths for build variants.
- Scripts in scripts/ handle bundling, packaging, testing, and CI build orchestration.
- mcp-server/ is its own Node/TypeScript package, separate from the main Bun runtime, meant specifically for source exploration through MCP clients.
14. How to diagram the data flow
- The main flow is: user input in Ink UI → command/input processing → query engine → permission check → tool execution or model response → state/UI update.
- Side flows include:
- CLI ↔ bridge ↔ IDE
- CLI ↔ remote/server session infrastructure
- CLI ↔ external services such as Anthropic API, OAuth, MCP, LSP, analytics, and plugins
- The key architectural boundary is that the model does not act directly; it proposes actions, and the tool/permission/service layers mediate execution.
Main entry points: QueryEngine.ts Query engine · claude.ts Services · App.tsx Ink UI · processUserInput.ts Input routing
Components 20
CLI runtime
Primary Bun/TypeScript agent loop and terminal UI.
- CLI entry · Bootstraps config, auth, flags, and launches the terminal app.
src/main.tsx - Ink UI · React + Ink screens, dialogs, message rendering, and input handling.
src/components/App.tsx - App state · Session, notification, modal, and cross-screen state coordination.
src/state/AppState.tsx - Input routing · Normalizes user input and routes slash commands versus prompt text.
src/utils/processUserInput/processUserInput.ts - Query engine · Drives model turns, streaming, retries, token accounting, and tool-use cycles.
src/QueryEngine.ts - Permission gate · Decides whether tool calls are allowed, denied, or require approval.
src/utils/permissions/permissions.ts - Tool exec · Streams and orchestrates tool execution and tool-result handling.
src/services/tools/StreamingToolExecutor.ts - Tools · Model-facing tool modules for file, shell, search, web, MCP, tasks, and agent actions.
src/tools.ts - Commands · Slash command registry and implementations for session and product control.
src/commands.ts - Services · Shared integrations for API, auth, MCP, LSP, analytics, plugins, compacting, and memory.
src/services/api/claude.ts - IDE bridge · Bidirectional bridge for editor integrations, permissions callbacks, and session messaging.
src/bridge/bridgeMain.ts - Remote sessions · Websocket and server-side session infrastructure for remote or browser access.
src/server/web/session-manager.ts - Memory & tasks · Session history, memories, background tasks, and long-running work continuity.
src/history.ts - Extensions · Plugin and skill loading plus packaged extension behaviors.
src/plugins/builtinPlugins.ts
Web app
Browser-native conversation and collaboration surface.
- Web app shell · Next.js browser surface for chat, files, sharing, export, and settings.
web/app/page.tsx - Web runtime · Chat layout, command palette, file viewer, collaboration, and notification components.
web/components/chat/ChatLayout.tsx - Web API · HTTP routes for chat, files, export, and sharing.
web/app/api/chat/route.ts - Web lib · Client API, collaboration sockets, export, search, storage, performance, and compatibility helpers.
web/lib/api/client.ts
MCP server
Standalone source-explorer server package.
- MCP server · Standalone MCP package exposing source exploration and HTTP/server entrypoints.
mcp-server/src/index.ts - MCP HTTP · HTTP transport and server wiring for the MCP source-explorer package.
mcp-server/src/http.ts
Connections 25
- CLI entry → Ink UI: launches · Bootstraps the terminal product and renders the Ink app.
- Ink UI → App state: reads/writes · UI components bind to shared application and session state.
- Ink UI → Input routing: captures input · Prompt box and keyboard handling feed normalized user input.
- Input routing → Commands: slash commands · Command input is dispatched to the control plane.
- Input routing → Query engine: prompt text · Natural-language input enters the agent loop.
- Query engine → Permission gate: checks · Tool proposals are filtered through approval and policy checks.
- Permission gate → Tool exec: allows · Approved tool calls proceed to execution.
- Query engine → Tool exec: requests · The agent loop issues tool calls and consumes streamed results.
- Tool exec → Tools: invokes · Execution targets the concrete tool modules.
- Query engine → App state: updates · Streaming turns and session state are reflected back into the UI state.
- Commands → Services: uses · Commands trigger auth, config, MCP, memory, plugin, and diagnostics services.
- Query engine → Services: depends on · Model calls and supporting infrastructure rely on shared services.
- Services → Memory & tasks: persists · Session memory and background work are managed through persistence services.
- IDE bridge → Services: syncs · Bridge sessions and editor callbacks rely on shared auth and session services.
- IDE bridge → Ink UI: coordinates · Editor/CLI synchronization affects terminal interaction and status views.
- Remote sessions → App state: hosts · Remote and web session infrastructure reflects the same session model.
- Remote sessions → Query engine: feeds · Remote sessions ultimately drive the same agent loop.
- Extensions → Tools: extends · Plugins and skills add capabilities to the tool and command surfaces.
- Extensions → Services: integrates · Extension loading and policy hooks depend on shared infrastructure.
- Web app shell → Web runtime: renders · The Next.js shell composes the browser-native UI.
- Web app shell → Web API: serves · The app exposes route handlers for chat, files, export, and share.
- Web runtime → Web lib: uses · UI components depend on shared client APIs and helpers.
- Web API → Web lib: delegates · Route handlers and browser workflows share data-access primitives.
- MCP server → MCP HTTP: hosts · The MCP package exposes source exploration over HTTP/server transport.
- MCP server → Services: adjacent to · The MCP package is separate but conceptually sits beside the main service layer.