# lazyjlbl/claude-code architecture

> Architecture diagram of the GitHub repository lazyjlbl/claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lazyjlbl/claude-code
- Repository: https://github.com/lazyjlbl/claude-code

## Overview

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: [`src/services/tools/toolExecution.ts`](https://github.com/lazyjlbl/claude-code/blob/main/src/services/tools/toolExecution.ts) (Tool execution), [`src/QueryEngine.ts`](https://github.com/lazyjlbl/claude-code/blob/main/src/QueryEngine.ts) (Query engine), [`src/components/App.tsx`](https://github.com/lazyjlbl/claude-code/blob/main/src/components/App.tsx) (App UI), [`src/context.ts`](https://github.com/lazyjlbl/claude-code/blob/main/src/context.ts) (Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core loop"]
  node_main["Main<br/>entrypoint<br/>[main.tsx]"]
  node_commands["Commands<br/>command registry<br/>[commands.ts]"]
  node_process_input["Input router<br/>input pipeline"]
  node_query_engine["Query engine<br/>LLM loop<br/>[QueryEngine.ts]"]
  node_context["Context<br/>[context.ts]"]
  node_compact["Compaction<br/>context management<br/>[compact.ts]"]
end

subgraph group_ui["Terminal UI"]
  node_ui_app["App UI<br/>terminal shell<br/>[App.tsx]"]
  node_prompt_input["Prompt input<br/>input widgets<br/>[PromptInput.tsx]"]
  node_messages["Messages<br/>renderers"]
  node_permissions_ui["Permissions UI<br/>approval dialogs"]
end

subgraph group_tools["Tools"]
  node_tool_registry["Tool registry<br/>tool catalog<br/>[tools.ts]"]
  node_tool_exec["Tool execution<br/>executor<br/>[toolExecution.ts]"]
  node_bash_tool["Shell tools<br/>[BashTool.tsx]"]
  node_file_tools["File tools<br/>fs tools<br/>[FileReadTool.ts]"]
  node_network_tools["Network tools<br/>[WebSearchTool.ts]"]
end

subgraph group_runtime["Runtime services"]
  node_agent_tools["Agent tools<br/>[AgentTool.tsx]"]
  node_tasks["Tasks<br/>task system<br/>[tasks.ts]"]
  node_plugins["Plugins<br/>extension loader<br/>[builtinPlugins.ts]"]
  node_session["Session storage<br/>persistence<br/>[history.ts]"]
end

subgraph group_ext["External systems"]
  node_api["API<br/>model client<br/>[client.ts]"]
  node_bridge["Bridge<br/>integration boundary<br/>[bridgeMain.ts]"]
  node_remote["Remote sessions<br/>remote control"]
end

node_main -->|"starts"| node_ui_app
node_ui_app -->|"renders"| node_prompt_input
node_ui_app -->|"renders"| node_messages
node_ui_app -->|"surfaces"| node_permissions_ui
node_prompt_input -->|"submits"| node_process_input
node_process_input -->|"routes /"| node_commands
node_process_input -->|"routes prompt"| node_query_engine
node_commands -->|"mutates loop"| node_query_engine
node_query_engine -->|"reads"| node_context
node_context -.->|"may compact"| node_compact
node_query_engine -->|"calls"| node_api
node_query_engine -->|"requests tools"| node_tool_registry
node_tool_registry -->|"executes via"| node_tool_exec
node_tool_exec -->|"checks approval"| node_permissions_ui
node_tool_exec -->|"runs shell"| node_bash_tool
node_tool_exec -->|"runs fs"| node_file_tools
node_tool_exec -->|"runs network"| node_network_tools
node_tool_exec -->|"spawns workers"| node_agent_tools
node_tool_exec -->|"records"| node_tasks
node_session -->|"restores"| node_context
node_session -->|"feeds loop"| node_query_engine
node_plugins -->|"extends"| node_commands
node_plugins -->|"extends"| node_tool_registry
node_plugins -.->|"injects"| node_context
node_bridge -->|"drives"| node_query_engine
node_bridge -.->|"callbacks"| node_permissions_ui
node_remote -->|"uses"| node_bridge
node_remote -->|"manages"| node_tasks

click node_main "https://github.com/lazyjlbl/claude-code/blob/main/src/main.tsx"
click node_commands "https://github.com/lazyjlbl/claude-code/blob/main/src/commands.ts"
click node_process_input "https://github.com/lazyjlbl/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts"
click node_query_engine "https://github.com/lazyjlbl/claude-code/blob/main/src/QueryEngine.ts"
click node_context "https://github.com/lazyjlbl/claude-code/blob/main/src/context.ts"
click node_compact "https://github.com/lazyjlbl/claude-code/blob/main/src/services/compact/compact.ts"
click node_api "https://github.com/lazyjlbl/claude-code/blob/main/src/services/api/client.ts"
click node_ui_app "https://github.com/lazyjlbl/claude-code/blob/main/src/components/App.tsx"
click node_prompt_input "https://github.com/lazyjlbl/claude-code/blob/main/src/components/PromptInput/PromptInput.tsx"
click node_messages "https://github.com/lazyjlbl/claude-code/blob/main/src/components/messages/AssistantTextMessage.tsx"
click node_permissions_ui "https://github.com/lazyjlbl/claude-code/blob/main/src/components/permissions/PermissionDialog.tsx"
click node_tool_registry "https://github.com/lazyjlbl/claude-code/blob/main/src/tools.ts"
click node_tool_exec "https://github.com/lazyjlbl/claude-code/blob/main/src/services/tools/toolExecution.ts"
click node_bash_tool "https://github.com/lazyjlbl/claude-code/blob/main/src/tools/BashTool/BashTool.tsx"
click node_file_tools "https://github.com/lazyjlbl/claude-code/blob/main/src/tools/FileReadTool/FileReadTool.ts"
click node_network_tools "https://github.com/lazyjlbl/claude-code/blob/main/src/tools/WebSearchTool/WebSearchTool.ts"
click node_agent_tools "https://github.com/lazyjlbl/claude-code/blob/main/src/tools/AgentTool/AgentTool.tsx"
click node_tasks "https://github.com/lazyjlbl/claude-code/blob/main/src/tasks.ts"
click node_plugins "https://github.com/lazyjlbl/claude-code/blob/main/src/plugins/builtinPlugins.ts"
click node_session "https://github.com/lazyjlbl/claude-code/blob/main/src/history.ts"
click node_bridge "https://github.com/lazyjlbl/claude-code/blob/main/src/bridge/bridgeMain.ts"
click node_remote "https://github.com/lazyjlbl/claude-code/blob/main/src/remote/RemoteSessionManager.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_commands,node_process_input,node_query_engine,node_context,node_compact toneBlue
class node_ui_app,node_prompt_input,node_messages,node_permissions_ui toneAmber
class node_tool_registry,node_tool_exec,node_bash_tool,node_file_tools,node_network_tools toneMint
class node_agent_tools,node_tasks,node_plugins,node_session toneRose
class node_api,node_bridge,node_remote toneIndigo
```

## Components

### Core loop

Session control, prompt routing, context, and model orchestration.

- [Main](https://github.com/lazyjlbl/claude-code/blob/main/src/main.tsx): entrypoint · Bootstraps the CLI and starts the app. · `src/main.tsx`
- [Commands](https://github.com/lazyjlbl/claude-code/blob/main/src/commands.ts): command registry · Registers and dispatches slash commands and CLI subcommands. · `src/commands.ts`
- [Input router](https://github.com/lazyjlbl/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts): input pipeline · Normalizes user input and routes it to commands, tools, or prompts. · `src/utils/processUserInput/processUserInput.ts`
- [Query engine](https://github.com/lazyjlbl/claude-code/blob/main/src/QueryEngine.ts): LLM loop · Runs the request/response loop, streams model output, and requests tool calls. · `src/QueryEngine.ts`
- [Context](https://github.com/lazyjlbl/claude-code/blob/main/src/context.ts): session context · Builds model context and session-scoped state. · `src/context.ts`
- [Compaction](https://github.com/lazyjlbl/claude-code/blob/main/src/services/compact/compact.ts): context management · 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](https://github.com/lazyjlbl/claude-code/blob/main/src/components/App.tsx): terminal shell · Root React/Ink application composition and screen layout. · `src/components/App.tsx`
- [Prompt input](https://github.com/lazyjlbl/claude-code/blob/main/src/components/PromptInput/PromptInput.tsx): input widgets · Command line input, history, shortcuts, and typing modes. · `src/components/PromptInput/PromptInput.tsx`
- [Messages](https://github.com/lazyjlbl/claude-code/blob/main/src/components/messages/AssistantTextMessage.tsx): renderers · Conversation, tool-use, system, and task message rendering. · `src/components/messages/AssistantTextMessage.tsx`
- [Permissions UI](https://github.com/lazyjlbl/claude-code/blob/main/src/components/permissions/PermissionDialog.tsx): approval dialogs · 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](https://github.com/lazyjlbl/claude-code/blob/main/src/tools.ts): tool catalog · Declares agent capabilities and tool boundaries. · `src/tools.ts`
- [Tool execution](https://github.com/lazyjlbl/claude-code/blob/main/src/services/tools/toolExecution.ts): executor · Streams and coordinates tool invocation and results. · `src/services/tools/toolExecution.ts`
- [Shell tools](https://github.com/lazyjlbl/claude-code/blob/main/src/tools/BashTool/BashTool.tsx): fs/shell tools · Bash and PowerShell execution with safety checks. · `src/tools/BashTool/BashTool.tsx`
- [File tools](https://github.com/lazyjlbl/claude-code/blob/main/src/tools/FileReadTool/FileReadTool.ts): fs tools · Read, write, edit, grep, glob, and notebook mutation tools. · `src/tools/FileReadTool/FileReadTool.ts`
- [Network tools](https://github.com/lazyjlbl/claude-code/blob/main/src/tools/WebSearchTool/WebSearchTool.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](https://github.com/lazyjlbl/claude-code/blob/main/src/tools/AgentTool/AgentTool.tsx): multi-agent tools · Subagent spawning, task management, team coordination, and messaging. · `src/tools/AgentTool/AgentTool.tsx`
- [Tasks](https://github.com/lazyjlbl/claude-code/blob/main/src/tasks.ts): task system · Background, remote, shell, and agent task tracking. · `src/tasks.ts`
- [Plugins](https://github.com/lazyjlbl/claude-code/blob/main/src/plugins/builtinPlugins.ts): extension loader · Loads plugins that add commands, tools, hooks, and output styles. · `src/plugins/builtinPlugins.ts`
- [Session storage](https://github.com/lazyjlbl/claude-code/blob/main/src/history.ts): persistence · History, resume, state, and session restoration. · `src/history.ts`

### External systems

APIs, shell/fs, MCP, IDE bridges, and remote/session backends.

- [API](https://github.com/lazyjlbl/claude-code/blob/main/src/services/api/client.ts): model client · External model and usage API integration layer. · `src/services/api/client.ts`
- [Bridge](https://github.com/lazyjlbl/claude-code/blob/main/src/bridge/bridgeMain.ts): integration boundary · IDE and REPL bridge for external control of sessions. · `src/bridge/bridgeMain.ts`
- [Remote sessions](https://github.com/lazyjlbl/claude-code/blob/main/src/remote/RemoteSessionManager.ts): remote control · Managed and direct-connect remote session infrastructure. · `src/remote/RemoteSessionManager.ts`

## Connections

- 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.
