How lazyjlbl/claude-code works
1. This repository is a TypeScript/Bun CLI application with a React + Ink terminal UI. The app is centered around an interactive session loop that renders screens/components in the terminal while driving LLM conversations, tool execution, and background tasks.
2. The top-level control plane is split across src/main.tsx, src/commands.ts, src/tools.ts, src/QueryEngine.ts, and src/context.ts. main.tsx boots the process, the command registry wires / commands, the tool registry exposes agent capabilities, and QueryEngine.ts is the core request/response loop for model interaction.
3. The primary user flow is: user input enters the CLI UI, is normalized by src/utils/processUserInput/*, routed through command handling or tool invocation, and then fed into the query engine. The query engine streams model output back into the UI, may request tool calls, and continues the loop until a final response is produced.
4. Tool execution is a major subsystem under src/tools/. Each tool is a boundary with its own schema, UI, and prompt/permission logic. The tool layer includes local system actions like bash, file read/write/edit, grep/glob, notebook edits, and LSP; networked actions like web search/fetch and MCP; and higher-level orchestration tools like agent spawning, task management, worktree/plan mode toggles, cron, and messaging.
5. Permissioning is a cross-cutting gate around tool use. src/hooks/toolPermission/ and src/components/permissions/ implement the policy/UX boundary that decides whether a tool call is auto-approved, denied, or surfaced to the user. This is where destructive shell actions, file writes, network access, and other sensitive operations are mediated before execution.
6. The UI is organized as a layered terminal application: reusable Ink primitives live in src/ink/, app-level state and context live in src/state/ and src/context/, and the visual experience is composed from src/components/. The components cover message rendering, prompt input, dialogs, status lines, task views, settings, onboarding, and specialized permission flows.
7. Session and conversation persistence are handled by several adjacent subsystems. src/assistant/sessionHistory.ts, src/history.ts, src/utils/sessionStorage*, src/utils/sessionState.ts, and src/utils/sessionRestore.ts maintain prior turns, resumable sessions, and local state. Context management is also explicit: src/context.ts, src/utils/context*, and src/services/compact/* gather, summarize, and compress information before it is sent to the model.
8. External model/API integrations are concentrated in src/services/api/, with supporting logic for retry, logging, usage tracking, and file/session ingress. The application also keeps cost and token awareness via src/cost-tracker.ts, src/services/tokenEstimation.ts, and related rate-limit/usage modules, which influence when compaction, warnings, or alternate flows are triggered.
9. The bridge subsystem under src/bridge/ is the integration boundary for IDE and remote-control scenarios. It includes messaging, session creation, permission callbacks, polling/config, and REPL bridge transport. This layer allows the CLI session to be driven from external editors or companion processes rather than only from the terminal UI.
10. Remote and multi-session behavior is first-class. src/remote/, src/server/, src/services/remoteManagedSettings/, and src/utils/remote* cover remote session management, direct-connect session creation, transport to WebSocket/session backends, and synced settings. These modules separate local interactive execution from remote or managed deployments.
11. Multi-agent and background execution are explicit architectural domains. src/coordinator/, src/tasks/, src/services/tools/toolOrchestration.ts, and the AgentTool/team tools provide the machinery for spawning subtasks, tracking task state, and coordinating concurrent workers. The UI exposes this through task/agent panels and progress components rather than folding everything into the main prompt loop.
12. Extension points are implemented as parallel systems: src/plugins/ and src/services/plugins/ load commands, tools, hooks, and output styles; src/skills/ provides reusable or user-defined workflows invoked through the skill tool; src/memdir/ and src/services/teamMemorySync/ manage persistent and shared memory. These are all separate from core commands/tools, but they inject behavior into startup, tool availability, and prompt context.
13. The repository also contains platform and environment adapters that materially affect architecture: src/keybindings/ and src/vim/ shape input handling, src/voice/ and src/services/voice* support voice mode, src/bridge/ and src/components/BridgeDialog.tsx support IDE integration, and src/upstreamproxy/ plus assorted auth/OAuth/keychain utilities handle credentials and transport. In diagram terms, these are edge adapters around the core session engine.
14. A useful diagram boundary is: terminal/UI state on one side, orchestration and policy in the middle, and external systems on the other side. The middle contains the command dispatcher, permission gate, query engine, tool executor, compaction/context services, and task/agent coordination; the external side includes Anthropic APIs, MCP servers, shell/FS, IDE bridges, OAuth/keychain, and remote session infrastructure.
Main entry points: toolExecution.ts Tool execution · QueryEngine.ts Query engine · App.tsx App UI · context.ts Context
Components 22
Core loop
Session control, prompt routing, context, and model orchestration.
- Main · Bootstraps the CLI and starts the app.
src/main.tsx - Commands · Registers and dispatches slash commands and CLI subcommands.
src/commands.ts - Input router · Normalizes user input and routes it to commands, tools, or prompts.
src/utils/processUserInput/processUserInput.ts - Query engine · Runs the request/response loop, streams model output, and requests tool calls.
src/QueryEngine.ts - Context · Builds model context and session-scoped state.
src/context.ts - Compaction · Summarizes and compresses long sessions before model calls.
src/services/compact/compact.ts
Terminal UI
Ink/React terminal interface, screens, components, and input handling.
- App UI · Root React/Ink application composition and screen layout.
src/components/App.tsx - Prompt input · Command line input, history, shortcuts, and typing modes.
src/components/PromptInput/PromptInput.tsx - Messages · Conversation, tool-use, system, and task message rendering.
src/components/messages/AssistantTextMessage.tsx - Permissions UI · User-facing permission prompts and approval workflows for tools.
src/components/permissions/PermissionDialog.tsx
Tools
Tool definitions, execution, permission gates, and user-facing tool flows.
- Tool registry · Declares agent capabilities and tool boundaries.
src/tools.ts - Tool execution · Streams and coordinates tool invocation and results.
src/services/tools/toolExecution.ts - Shell tools · Bash and PowerShell execution with safety checks.
src/tools/BashTool/BashTool.tsx - File tools · Read, write, edit, grep, glob, and notebook mutation tools.
src/tools/FileReadTool/FileReadTool.ts - Network tools · Web search/fetch and MCP networked tool boundaries.
src/tools/WebSearchTool/WebSearchTool.ts
Runtime services
Persistence, remote control, plugins, tasks, and background coordination.
- Agent tools · Subagent spawning, task management, team coordination, and messaging.
src/tools/AgentTool/AgentTool.tsx - Tasks · Background, remote, shell, and agent task tracking.
src/tasks.ts - Plugins · Loads plugins that add commands, tools, hooks, and output styles.
src/plugins/builtinPlugins.ts - Session storage · History, resume, state, and session restoration.
src/history.ts
External systems
APIs, shell/fs, MCP, IDE bridges, and remote/session backends.
- API · External model and usage API integration layer.
src/services/api/client.ts - Bridge · IDE and REPL bridge for external control of sessions.
src/bridge/bridgeMain.ts - Remote sessions · Managed and direct-connect remote session infrastructure.
src/remote/RemoteSessionManager.ts
Connections 28
- Main → App UI: starts · Bootstraps the terminal app.
- App UI → Prompt input: renders · Hosts the user input surface.
- App UI → Messages: renders · Displays conversation and tool results.
- App UI → Permissions UI: surfaces · Shows approval and trust dialogs.
- Prompt input → Input router: submits · User keystrokes become normalized actions.
- Input router → Commands: routes / · Slash commands are dispatched to the registry.
- Input router → Query engine: routes prompt · Plain text becomes a model request.
- Commands → Query engine: mutates loop · Commands can affect the active session and model flow.
- Query engine → Context: reads · Builds prompts from session context.
- Context → Compaction: may compact · Long context is summarized before model calls.
- Query engine → API: calls · Sends prompts and receives streamed model output.
- Query engine → Tool registry: requests tools · Model responses can trigger tool use.
- Tool registry → Tool execution: executes via · Registered tools are handed to the executor.
- Tool execution → Permissions UI: checks approval · Sensitive actions pass through the permission boundary.
- Tool execution → Shell tools: runs shell · Shell-oriented tools execute through this boundary.
- Tool execution → File tools: runs fs · File and search tools execute through this boundary.
- Tool execution → Network tools: runs network · Web and MCP tools execute through this boundary.
- Tool execution → Agent tools: spawns workers · Subagents and task tools are coordinated here.
- Tool execution → Tasks: records · Tool activity is tracked as background or remote tasks.
- Session storage → Context: restores · Prior turns and state are loaded into the current session.
- Session storage → Query engine: feeds loop · Resumed sessions re-enter the model loop.
- Plugins → Commands: extends · Plugins can contribute commands.
- Plugins → Tool registry: extends · Plugins can contribute tools.
- Plugins → Context: injects · Plugin hooks and output styles affect model context.
- Bridge → Query engine: drives · External controllers can initiate or steer sessions.
- Bridge → Permissions UI: callbacks · Bridge can participate in permission decisions.
- Remote sessions → Bridge: uses · Remote control flows build on bridge/session plumbing.
- Remote sessions → Tasks: manages · Remote work is tracked as sessions and tasks.