How yasasbanukaofficial/claude-code works
1. What this repo is
- This is a large TypeScript/React-based terminal application built around an AI coding agent. The runtime is centered on Bun/Node, with Ink providing the terminal UI layer and a command-driven CLI surface.
2. Primary entrypoints and boot path
- src/main.tsx, src/entrypoints/cli.tsx, src/setup.ts, and src/bootstrap/* form the startup path.
- These files likely initialize configuration, load plugins/skills, restore session state, set up auth/settings, and then mount the main app in the terminal renderer.
3. UI shell vs. agent core
- src/components/*, src/screens/*, src/ink/*, and src/keybindings/* are the presentation layer.
- src/state/*, src/context/*, and many hooks under src/hooks/* hold the interactive state machine, global context, command queue, notifications, and keyboard/input handling.
- The UI is not a typical web app; it is a terminal-first React app with custom layout/rendering primitives.
4. Core conversation and execution loop
- src/QueryEngine.ts, src/assistant/*, src/history.ts, src/tasks.ts, src/utils/processUserInput/*, and src/utils/messages/* appear to drive the agent loop:
user input -> classify/parse -> build prompt/context -> send to model -> receive assistant/tool events -> render messages and update history.
- This is the central data flow of the app and the main boundary between UI state and model/tool execution.
5. Tool system
- src/tools/*, src/Tool.ts, and src/constants/tools.ts define the tool catalog and tool contract.
- Tools cover file operations, shell execution, web search/fetch, LSP, MCP resources, task/subagent management, planning, memory, and remote triggers.
- src/services/tools/* handles orchestration and streaming execution, so tool calls are executed incrementally and feed progress/results back into the UI.
6. Permissions and safety boundary
- src/components/permissions/*, src/hooks/toolPermission/*, src/utils/permissions/*, src/services/policyLimits/*, and the Bash/PowerShell validation utilities enforce what the agent can do.
- This boundary is important: tool execution is gated by permission prompts, rule matching, sandbox checks, destructive-command detection, filesystem/path validation, and mode-dependent policies.
7. Remote control and bridge layer
- src/bridge/*, src/remote/*, src/server/*, and src/commands/bridge* implement IDE/remote-session integration and bridge transport.
- This layer appears to connect the local terminal app to external controllers, sessions, or background workers through WebSocket/SSE/REPL-style transports and session runners.
- It likely carries inbound messages, attachments, permissions callbacks, and session state across process or device boundaries.
8. Multi-agent and task orchestration
- src/coordinator/*, src/tasks/*, src/tools/AgentTool/*, src/utils/swarm/*, and src/components/tasks/* model autonomous sub-agents and background work.
- There are distinct task types for local shell, local agent, remote agent, dream/background work, and in-process teammates.
- The architecture suggests a hierarchical agent system: the main session can spawn specialized agents, track their progress, and merge their outputs back into the parent conversation.
9. External integrations
- MCP: src/services/mcp/*, src/commands/mcp/*, src/components/mcp/*, and MCP-related tools expose Model Context Protocol servers/clients and resource approval flows.
- Plugins/skills: src/services/plugins/*, src/utils/plugins/*, src/skills/*, and src/components/plugin/* provide extensibility and marketplace-style discovery/installation.
- Auth/OAuth and analytics: src/services/oauth/*, src/services/api/*, and src/services/analytics/* show cloud-backed authentication, usage reporting, and telemetry.
- LSP and editor integration: src/services/lsp/*, src/tools/LSPTool/*, and src/components/ide/* support code intelligence and IDE connection.
10. Memory, compaction, and background maintenance
- src/services/compact/*, src/services/SessionMemory/*, src/services/autoDream/*, src/memdir/*, and src/utils/memory/* manage durable memory and context reduction.
- These services read/write memory files, summarize sessions, compact long conversations, and periodically consolidate signal into smaller durable state.
- This is a key architecture boundary: long-lived session knowledge is separated from transient chat context.
11. Model/prompt/configuration layer
- src/constants/*, src/utils/model/*, src/utils/systemPrompt*, src/services/claudeAiLimits.ts, src/services/tokenEstimation.ts, and src/utils/config* shape how prompts are built and which models/capabilities are available.
- This layer controls model selection, token budget, prompting policy, and feature gating across the app.
12. Persistence and state stores
- src/utils/sessionStorage*, src/utils/settings/*, src/utils/filePersistence/*, src/utils/cachePaths.ts, src/utils/secureStorage/*, and src/state/AppStateStore.ts indicate a mix of local durable storage and in-memory app state.
- The app persists settings, auth, session history, caches, plugin state, and some secure credentials locally, while the live session state remains in the React/store layer.
13. Command surface
- src/commands/* is a large command registry for the CLI, covering session management, login/logout, config, plugins, bridge, resume, status, review, sandbox, export, and many specialized workflows.
- These commands are the user-facing control plane around the core assistant runtime.
14. Overall architectural shape
- The repo is best understood as a terminal-hosted agent platform with four major planes:
1. Interactive UI/runtime in Ink/React
2. Agent execution engine for prompts, tools, and tasks
3. Integration plane for IDE, MCP, plugins, remote sessions, auth, and telemetry
4. Safety/persistence plane for permissions, sandboxing, memory, settings, and session storage
- For a diagram, the main arrows run from user input and external events into the UI/state layer, then into the query/tool orchestration layer, and back out through messages, task updates, and remote/bridge transports.
Main entry points: toolOrchestration.ts Tool Exec · QueryEngine.ts Query Loop · App.tsx App Shell · AppStateStore.ts App State
Components 23
Runtime
Startup, CLI surface, and terminal renderer
UI Shell
Ink/React presentation and interaction state
- App Shell · Main app screen, prompt, messages, dialogs
src/components/App.tsx - App State · Global session and UI state store
src/state/AppStateStore.ts - Input Flow · User input, keybindings, and queued commands
src/hooks/useCommandQueue.ts
Agent Engine
Conversation loop, prompts, history, and task execution
- Query Loop · Builds prompts, sends requests, and applies model responses
src/QueryEngine.ts - History · Transcript and session history management
src/history.ts - Task System · Session, shell, agent, and remote task tracking
src/tasks.ts
Tools
Tool catalog and execution/orchestration
- Tool Catalog · Tool contracts and available capabilities
src/Tool.ts - Tool Exec · Streaming tool execution and lifecycle coordination
src/services/tools/toolOrchestration.ts - Shell Tools · Bash, PowerShell, file, search, and edit tools
src/tools/BashTool/BashTool.tsx - Agent Tools · Subagent spawning, planning, and task delegation tools
src/tools/AgentTool/AgentTool.tsx
Integrations
Remote control, MCP, plugins, LSP, auth, and telemetry
- Bridge · Local/remote bridge transport and session runner
src/bridge/bridgeMain.ts - Remote Sessions · Remote session manager and session transport
src/remote/RemoteSessionManager.ts - MCP · Model Context Protocol clients, servers, and approval flows
src/services/mcp/MCPConnectionManager.tsx - Plugins · Plugin discovery, loading, installation, and policy
src/services/plugins/PluginInstallationManager.ts - LSP · Language server integration and diagnostics
src/services/lsp/LSPServerManager.ts - Auth & Telemetry · OAuth, API client, analytics, and usage reporting
src/services/oauth/client.ts
State & Safety
Persistence, permissions, memory, settings, and policy
- Permissions · Permission prompts, rule matching, sandbox, and policy limits
src/utils/permissions/permissions.ts - Memory · Session memory, compaction, and memory files
src/services/SessionMemory/sessionMemory.ts - Persistence · Settings, session storage, secure storage, and caches
src/utils/sessionStorage.ts - Prompts · System prompts, model config, and token budgeting
src/utils/systemPrompt.ts
Connections 27
- Startup → CLI: boot · CLI startup enters the command surface
- Startup → Ink Core: mount · Bootstraps the terminal renderer
- CLI → App Shell: launch · Commands can open the interactive terminal app
- Ink Core → App Shell: render · Ink hosts the React terminal UI
- App Shell → App State: read/write · UI consumes and updates shared app state
- Input Flow → Query Loop: submit · User input is normalized into agent requests
- App State → Input Flow: drive · State powers prompt input, shortcuts, and queued actions
- Query Loop → Prompts: build prompt · Query engine assembles context and policy for the model
- Query Loop → History: append · Model turns and events are recorded in history
- Query Loop → Tool Exec: invoke tools · Assistant tool calls are executed through the tool runner
- Tool Exec → Tool Catalog: resolve · Tool runner dispatches by tool contract
- Tool Exec → Shell Tools: run · File, shell, and search operations execute here
- Tool Exec → Agent Tools: spawn · Delegates work to subagents and task tools
- Tool Exec → Task System: track · Tool activity feeds task progress and completion
- Task System → App Shell: report · Task state is surfaced back into the UI
- Bridge → Remote Sessions: connect · Bridge transport carries remote session traffic
- Bridge → App Shell: events · Inbound bridge messages affect local UI and permissions
- Remote Sessions → Task System: host · Remote sessions appear as tracked tasks
- MCP → Tool Exec: serve tools · MCP resources and approvals feed the tool layer
- Plugins → Tool Catalog: extend · Plugins add commands, tools, hooks, and styles
- Plugins → App Shell: augment UI · Plugin state and discovery affect the terminal interface
- LSP → Shell Tools: support · Code intelligence complements file and edit workflows
- Auth & Telemetry → Persistence: store creds · Authentication state is persisted locally
- Permissions → Tool Exec: gate · Permissions and sandbox policy approve or deny actions
- Memory → Query Loop: context · Long-lived memory is injected into the agent loop
- Persistence → App State: restore · Settings and session data hydrate runtime state
- Prompts → Query Loop: shape · Prompt and model policy constrain generation