# kuberwastaken/claude-code architecture

> Architecture diagram of the GitHub repository kuberwastaken/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/kuberwastaken/claude-code
- Repository: https://github.com/kuberwastaken/claude-code

## Overview

1. This repository is a monorepo-style TypeScript/Bun CLI application for Claude Code. The top-level runtime starts in `main.tsx` / `entrypoints/cli.tsx`, then fans out into command handlers, the terminal UI, tool execution, background services, and optional remote/bridge modes.

2. The core execution loop is a conversational agent loop: user input enters through the CLI/UI layer, gets parsed into commands or prompts, then is turned into model/tool requests. `state/`, `context/`, `hooks/`, and `services/tools/` coordinate that loop, while `tools/` contains the actual action implementations the model can invoke.

3. The terminal UI is built on a custom Ink-like renderer under `ink/`, with React components in `components/` and `screens/` driving the visible app. This layer owns prompt input, transcript rendering, dialogs, keybindings, notifications, and status indicators, but it does not directly implement business logic; it mostly reflects and manipulates app state.

4. Command handling is split into two layers: `commands/` contains user-facing slash commands and full-screen flows, while `cli/handlers/` handles CLI subcommands and noninteractive entry paths. `commands.ts` acts as the registry/dispatch surface. This is the main boundary between “interactive app features” and “operational CLI utilities.”

5. Tooling is a major subsystem. `tools/` defines dozens of model-callable capabilities: shell execution, file read/write/edit, web search/fetch, LSP integration, MCP access, agent spawning, task management, notebook edits, and remote triggers. Each tool typically has its own prompt, UI wrapper, validation, and result rendering, so the model sees a curated interface rather than raw host APIs.

6. Permissioning and safety form a separate control plane around tools. `utils/permissions/`, `hooks/toolPermission/`, and `components/permissions/` implement mode selection, path/risk validation, user approval dialogs, and auto-approval logic. The security boundary is especially important for shell and filesystem tools, where command semantics, sandboxing, and protected-file rules prevent unsafe actions.

7. Model and API access are abstracted through `services/api/`, `utils/model/`, `constants/`, and `QueryEngine.ts`. These layers assemble prompts, beta flags, context limits, model routing, cost tracking, and Anthropic-specific request metadata. The app depends on Anthropic’s API as the primary external model service, but wraps it with caching, retries, prompt composition, and feature gating.

8. Remote and multi-session behavior is a second major boundary. `bridge/`, `remote/`, `server/`, `upstreamproxy/`, `replLauncher.tsx`, and related hooks handle remote control sessions, CCR/bridge flows, websocket/session relays, trusted-device/JWT auth, and worktree or same-directory execution modes. This is where local terminal state can be mirrored, resumed, or controlled from another client.

9. Background intelligence and persistence are handled by dedicated services. `services/autoDream/`, `services/compact/`, `services/SessionMemory/`, `services/extractMemories/`, `memdir/`, and `history.ts` manage transcript summarization, memory consolidation, pruning, and retrieval. The data flow here is from session history and logs into durable memory files, then back into future prompts and context selection.

10. Plugins, skills, and MCP are extensibility layers. `plugins/`, `skills/`, `services/mcp/`, and `tools/MCPTool` support loading third-party or bundled capabilities, registering commands/tools/hooks, and connecting to external MCP servers. This expands the agent’s action surface without baking every integration into the core runtime.

11. Several subsystems are explicitly feature-gated or environment-gated. `migrations/`, `constants/betas.ts`, `utils/plugins/*`, `buddy/`, `coordinator/`, `voice/`, and some commands/hooks are only enabled for certain builds, org types, or runtime flags. Architecturally, this means the repository contains both public and internal product paths, with compile-time dead-code elimination used to produce different shipped binaries.

12. Telemetry, analytics, and operational safeguards are cross-cutting concerns. `services/analytics/`, `utils/telemetry/`, `utils/log.ts`, `utils/debug.ts`, `services/notifier.ts`, and `utils/diagnosticTracking.ts` collect events, traces, and usage signals. These systems feed product analytics, debugging, rate-limit handling, and session observability without being part of the core conversational loop.

13. If you’re drawing the architecture, the cleanest high-level split is: local CLI/UI frontend, agent/tool orchestration layer, safety/permission layer, model/API boundary, background memory/persistence services, and optional remote/extension boundaries. Most other directories hang off one of those six pillars.

Main entry points: [`services/tools/toolOrchestration.ts`](https://github.com/kuberwastaken/claude-code/blob/main/services/tools/toolOrchestration.ts) (Tool Orchestrator), [`hooks/useMainLoopModel.ts`](https://github.com/kuberwastaken/claude-code/blob/main/hooks/useMainLoopModel.ts) (Hooks), [`components/App.tsx`](https://github.com/kuberwastaken/claude-code/blob/main/components/App.tsx) (App Shell), [`state/store.ts`](https://github.com/kuberwastaken/claude-code/blob/main/state/store.ts) (State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontend["CLI & UI"]
  node_main_entry["Main<br/>entrypoint<br/>[main.tsx]"]
  node_cli_entry["CLI Entry<br/>entrypoint<br/>[cli.tsx]"]
  node_repl_screen["REPL<br/>screen<br/>[REPL.tsx]"]
  node_ink_runtime["Ink UI<br/>renderer<br/>[ink.tsx]"]
  node_app_shell["App Shell<br/>ui root<br/>[App.tsx]"]
end

subgraph group_grp_agent["Agent Core"]
  node_commands_registry["Commands<br/>dispatch<br/>[commands.ts]"]
  node_process_input["Input Parse<br/>input pipeline"]
  node_state_store[("State<br/>store<br/>[store.ts]")]
  node_context_layer(("Context<br/>[context.ts]"))
  node_hook_plane(("Hooks"))
end

subgraph group_grp_tools["Tools"]
  node_tool_orch["Tool Orchestrator<br/>execution engine"]
  node_bash_tool["Shell Tool<br/>[BashTool.tsx]"]
  node_fs_tool["File Tools<br/>tool suite<br/>[FileEditTool.ts]"]
  node_search_tools["Search Tools<br/>tool suite<br/>[WebSearchTool.ts]"]
end

subgraph group_grp_remote["Remote & Sessions"]
  node_bridge_remote["Bridge<br/>remote control<br/>[bridgeMain.ts]"]
  node_remote_server["Remote Server<br/>session relay"]
end

subgraph group_grp_persistence["Memory & Persistence"]
  node_memory_services["Memory<br/>persistence<br/>[sessionMemory.ts]"]
  node_history_store[("History<br/>transcript store<br/>[history.ts]")]
end

subgraph group_grp_platform["Platform Services"]
  node_model_api["Model API<br/>api boundary<br/>[claude.ts]"]
  node_permissions["Permissions<br/>control plane<br/>[permissions.ts]"]
  node_plugins_mcp["Plugins & MCP<br/>extension layer"]
  node_telemetry["Telemetry<br/>observability<br/>[index.ts]"]
end

node_main_entry -->|"boot"| node_cli_entry
node_cli_entry -->|"start UI"| node_app_shell
node_cli_entry -->|"launch"| node_repl_screen
node_app_shell -->|"rendered by"| node_ink_runtime
node_repl_screen -->|"compose"| node_app_shell
node_app_shell -->|"reads/writes"| node_state_store
node_context_layer -->|"shares"| node_state_store
node_hook_plane -->|"subscribes"| node_state_store
node_process_input -->|"slash cmds"| node_commands_registry
node_process_input -->|"prompt flow"| node_hook_plane
node_hook_plane -->|"requests"| node_model_api
node_model_api -->|"tool calls"| node_tool_orch
node_tool_orch -->|"executes"| node_bash_tool
node_tool_orch -->|"executes"| node_fs_tool
node_tool_orch -->|"executes"| node_search_tools
node_permissions -->|"gates"| node_bash_tool
node_permissions -->|"gates"| node_fs_tool
node_bridge_remote -->|"relays"| node_remote_server
node_bridge_remote -->|"mirrors"| node_state_store
node_memory_services -->|"persists"| node_history_store
node_hook_plane -->|"compact/extract"| node_memory_services
node_plugins_mcp -->|"extends"| node_tool_orch
node_plugins_mcp -->|"registers"| node_commands_registry
node_telemetry -->|"observes"| node_model_api
node_telemetry -->|"observes"| node_tool_orch

click node_main_entry "https://github.com/kuberwastaken/claude-code/blob/main/main.tsx"
click node_cli_entry "https://github.com/kuberwastaken/claude-code/blob/main/entrypoints/cli.tsx"
click node_repl_screen "https://github.com/kuberwastaken/claude-code/blob/main/screens/REPL.tsx"
click node_ink_runtime "https://github.com/kuberwastaken/claude-code/blob/main/ink/ink.tsx"
click node_app_shell "https://github.com/kuberwastaken/claude-code/blob/main/components/App.tsx"
click node_commands_registry "https://github.com/kuberwastaken/claude-code/blob/main/commands.ts"
click node_process_input "https://github.com/kuberwastaken/claude-code/blob/main/utils/processUserInput/processUserInput.ts"
click node_state_store "https://github.com/kuberwastaken/claude-code/blob/main/state/store.ts"
click node_context_layer "https://github.com/kuberwastaken/claude-code/blob/main/context.ts"
click node_hook_plane "https://github.com/kuberwastaken/claude-code/blob/main/hooks/useMainLoopModel.ts"
click node_model_api "https://github.com/kuberwastaken/claude-code/blob/main/services/api/claude.ts"
click node_tool_orch "https://github.com/kuberwastaken/claude-code/blob/main/services/tools/toolOrchestration.ts"
click node_bash_tool "https://github.com/kuberwastaken/claude-code/blob/main/tools/BashTool/BashTool.tsx"
click node_fs_tool "https://github.com/kuberwastaken/claude-code/blob/main/tools/FileEditTool/FileEditTool.ts"
click node_search_tools "https://github.com/kuberwastaken/claude-code/blob/main/tools/WebSearchTool/WebSearchTool.ts"
click node_permissions "https://github.com/kuberwastaken/claude-code/blob/main/utils/permissions/permissions.ts"
click node_bridge_remote "https://github.com/kuberwastaken/claude-code/blob/main/bridge/bridgeMain.ts"
click node_remote_server "https://github.com/kuberwastaken/claude-code/blob/main/server/directConnectManager.ts"
click node_memory_services "https://github.com/kuberwastaken/claude-code/blob/main/services/SessionMemory/sessionMemory.ts"
click node_history_store "https://github.com/kuberwastaken/claude-code/blob/main/history.ts"
click node_plugins_mcp "https://github.com/kuberwastaken/claude-code/blob/main/services/plugins/PluginInstallationManager.ts"
click node_telemetry "https://github.com/kuberwastaken/claude-code/blob/main/services/analytics/index.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_entry,node_cli_entry,node_repl_screen,node_ink_runtime,node_app_shell toneBlue
class node_commands_registry,node_process_input,node_state_store,node_context_layer,node_hook_plane toneAmber
class node_tool_orch,node_bash_tool,node_fs_tool,node_search_tools toneMint
class node_bridge_remote,node_remote_server toneRose
class node_memory_services,node_history_store toneIndigo
class node_model_api,node_permissions,node_plugins_mcp,node_telemetry toneTeal
```

## Components

### CLI & UI

Interactive terminal entrypoints, React screens, and Ink renderer.

- [Main](https://github.com/kuberwastaken/claude-code/blob/main/main.tsx): entrypoint · Top-level runtime bootstrap for the CLI app. · `main.tsx`
- [CLI Entry](https://github.com/kuberwastaken/claude-code/blob/main/entrypoints/cli.tsx): entrypoint · CLI startup and subcommand wiring. · `entrypoints/cli.tsx`
- [REPL](https://github.com/kuberwastaken/claude-code/blob/main/screens/REPL.tsx): screen · Primary terminal conversation surface. · `screens/REPL.tsx`
- [Ink UI](https://github.com/kuberwastaken/claude-code/blob/main/ink/ink.tsx): renderer · Custom terminal renderer and event/layout system. · `ink/ink.tsx`
- [App Shell](https://github.com/kuberwastaken/claude-code/blob/main/components/App.tsx): ui root · Top-level React app and UI composition. · `components/App.tsx`

### Agent Core

Conversation loop, state, context, commands, and tool orchestration.

- [Commands](https://github.com/kuberwastaken/claude-code/blob/main/commands.ts): dispatch · Registry and dispatch surface for slash commands. · `commands.ts`
- [Input Parse](https://github.com/kuberwastaken/claude-code/blob/main/utils/processUserInput/processUserInput.ts): input pipeline · Turns user text, slash commands, and shell input into actions. · `utils/processUserInput/processUserInput.ts`
- [State](https://github.com/kuberwastaken/claude-code/blob/main/state/store.ts): store · App state, selectors, and store coordination. · `state/store.ts`
- [Context](https://github.com/kuberwastaken/claude-code/blob/main/context.ts): context · Shared app contexts for prompt, overlays, notifications, and queueing. · `context.ts`
- [Hooks](https://github.com/kuberwastaken/claude-code/blob/main/hooks/useMainLoopModel.ts): react hooks · Lifecycle, command, tool, IDE, and queue hooks that drive the loop. · `hooks/useMainLoopModel.ts`

### Tools

Model-callable actions and their shared execution boundaries.

- [Tool Orchestrator](https://github.com/kuberwastaken/claude-code/blob/main/services/tools/toolOrchestration.ts): execution engine · Streaming tool execution, orchestration, and tool hooks. · `services/tools/toolOrchestration.ts`
- [Shell Tool](https://github.com/kuberwastaken/claude-code/blob/main/tools/BashTool/BashTool.tsx): tool · Shell execution with semantics, sandboxing, and permission checks. · `tools/BashTool/BashTool.tsx`
- [File Tools](https://github.com/kuberwastaken/claude-code/blob/main/tools/FileEditTool/FileEditTool.ts): tool suite · Read/write/edit and notebook/file boundary tools. · `tools/FileEditTool/FileEditTool.ts`
- [Search Tools](https://github.com/kuberwastaken/claude-code/blob/main/tools/WebSearchTool/WebSearchTool.ts): tool suite · Glob, grep, web, and resource lookup capabilities. · `tools/WebSearchTool/WebSearchTool.ts`

### Remote & Sessions

Bridge, server, and relay paths for multi-session control.

- [Bridge](https://github.com/kuberwastaken/claude-code/blob/main/bridge/bridgeMain.ts): remote control · Bridge protocol, session relay, and remote control flows. · `bridge/bridgeMain.ts`
- [Remote Server](https://github.com/kuberwastaken/claude-code/blob/main/server/directConnectManager.ts): session relay · Direct-connect and websocket session infrastructure. · `server/directConnectManager.ts`

### Memory & Persistence

Summaries, memory files, history, and compaction pipelines.

- [Memory](https://github.com/kuberwastaken/claude-code/blob/main/services/SessionMemory/sessionMemory.ts): persistence · Session memory, compaction, extraction, and durable recall. · `services/SessionMemory/sessionMemory.ts`
- [History](https://github.com/kuberwastaken/claude-code/blob/main/history.ts): transcript store · Conversation history and replay-related persistence. · `history.ts`

### Platform Services

Model/API access, permissions, plugins, telemetry, and supporting services.

- [Model API](https://github.com/kuberwastaken/claude-code/blob/main/services/api/claude.ts): api boundary · Prompt assembly, routing, retries, limits, and Anthropic requests. · `services/api/claude.ts`
- [Permissions](https://github.com/kuberwastaken/claude-code/blob/main/utils/permissions/permissions.ts): control plane · Approval dialogs, rules, and auto-approval logic. · `utils/permissions/permissions.ts`
- [Plugins & MCP](https://github.com/kuberwastaken/claude-code/blob/main/services/plugins/PluginInstallationManager.ts): extension layer · Plugin loading, skills, and MCP integration. · `services/plugins/PluginInstallationManager.ts`
- [Telemetry](https://github.com/kuberwastaken/claude-code/blob/main/services/analytics/index.ts): observability · Analytics, logging, diagnostics, and usage tracking. · `services/analytics/index.ts`

## Connections

- Main → CLI Entry: boot · Main runtime hands off to CLI entrypaths.
- CLI Entry → App Shell: start UI · Interactive mode mounts the app shell.
- CLI Entry → REPL: launch · REPL and resume modes enter the terminal conversation screen.
- App Shell → Ink UI: rendered by · React UI is rendered through the custom Ink runtime.
- REPL → App Shell: compose · Screen content is composed inside the app shell.
- App Shell → State: reads/writes · UI reflects and updates central app state.
- Context → State: shares · Contexts carry state-adjacent coordination data.
- Hooks → State: subscribes · Hooks drive stateful behavior and lifecycle effects.
- Input Parse → Commands: slash cmds · User commands are parsed and dispatched through the registry.
- Input Parse → Hooks: prompt flow · Prompt and input processing feed the agent loop hooks.
- Hooks → Model API: requests · Loop hooks assemble prompts and call the model boundary.
- Model API → Tool Orchestrator: tool calls · Model responses are translated into tool execution requests.
- Tool Orchestrator → Shell Tool: executes · Shell actions are routed to the shell tool.
- Tool Orchestrator → File Tools: executes · Filesystem edits and reads are routed to file tools.
- Tool Orchestrator → Search Tools: executes · Search and fetch actions are routed to search-oriented tools.
- Permissions → Shell Tool: gates · Shell execution is mediated by permission and sandbox rules.
- Permissions → File Tools: gates · File operations pass through approval and safety checks.
- Bridge → Remote Server: relays · Bridge flows connect local sessions to remote control paths.
- Bridge → State: mirrors · Remote control mirrors session state and UI updates.
- Memory → History: persists · Summaries and memories are derived from transcript history.
- Hooks → Memory: compact/extract · Background hooks trigger memory consolidation and compaction.
- Plugins & MCP → Tool Orchestrator: extends · Plugins and MCP add commands, tools, and hooks to execution.
- Plugins & MCP → Commands: registers · Extension systems can add user-facing commands.
- Telemetry → Model API: observes · Model and API activity is instrumented for analytics and diagnostics.
- Telemetry → Tool Orchestrator: observes · Tool execution and failures feed observability pipelines.
