# nicole-yi/claude-code-restored architecture

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

## Overview

1. This repository is a restored, runnable TypeScript/Bun codebase for the Claude Code CLI. The architectural center is a terminal-based agent application, not a web server: `src/main.tsx` and `src/entrypoints/cli.tsx` bootstrap the CLI, then the REPL-style runtime drives prompts, tool calls, permissions, and session state.

2. The top-level flow is: command parsing and startup setup → app state initialization → Ink-based terminal UI → agent loop. `src/dev-entry.ts`, `src/setup.ts`, `src/bootstrap/`, and `src/state/` prepare config, auth, caches, and persistent state before the interactive session starts. The app state layer is the main coordination boundary for UI, tools, sessions, and background services.

3. The UI layer is terminal-native and built on a custom Ink implementation under `src/ink/`. This is a major boundary in the repo: rendering, layout, focus, terminal events, ANSI handling, and virtual scrolling are handled locally rather than by upstream Ink alone. Higher-level UI lives in `src/components/`, with React/TSX for messages, dialogs, permissions, prompts, status lines, diffs, settings, and task views.

4. The assistant conversation model is represented by `src/history.ts`, `src/context/`, `src/assistant/`, `src/query/`, and message components. User input, tool output, assistant text, thinking, and system notices are normalized into structured message streams, then rendered in the terminal and used to build the next model request. Session discovery/history modules support resuming and cross-session navigation.

5. Tool execution is a first-class subsystem under `src/tools/` and `src/services/tools/`. The repo has many specialized tools: shell execution, file read/write/edit, search, web fetch/search/browser, MCP access, task management, skill invocation, workflow control, and multi-agent operations. The important boundary is that tools are not UI widgets; each tool has its own execution logic, permission model, prompt schema, and UI representation.

6. Permissioning and safety are central. `src/hooks/toolPermission/`, `src/components/permissions/`, and `src/utils/permissions/` define the request/decision flow for risky actions such as shell commands, file edits, sandbox access, and computer use. This layer also contains classifier-based or rule-based automation, denial tracking, and mode transitions such as plan mode or bypass modes.

7. The services layer contains most external integrations and runtime policies. `src/services/api/` wraps Anthropic API access, retries, rate limits, usage, and logging. `src/services/mcp/` implements MCP client/server behavior, OAuth, channel policies, and connection management. `src/services/analytics/`, `src/services/oauth/`, `src/services/lsp/`, and `src/services/compact/` handle telemetry, authentication, IDE/language-server integration, and session compression.

8. Session and context management are separate concerns. `src/services/compact/`, `src/services/contextCollapse/`, `src/memdir/`, `src/services/SessionMemory/`, and `src/services/extractMemories/` decide what parts of the transcript, memories, files, and task outputs remain in context. These services feed the query engine so long-running sessions can continue despite token limits.

9. Remote and distributed operation is a distinct subsystem. `src/bridge/` handles remote control, session ingress, websocket/repl bridge modes, trust, webhook sanitization, and device/session identity. `src/remote/`, `src/server/`, `src/ssh/`, and `src/upstreamproxy/` support remote sessions, direct-connect servers, SSH-backed environments, and relayed traffic. This boundary is where local CLI state becomes networked session control.

10. Multi-agent and swarm behavior are supported through `src/coordinator/`, `src/tasks/`, `src/tools/AgentTool/`, and `src/utils/swarm/`. The coordinator/worker split lets the app spawn teammate agents, manage background tasks, and display their progress separately from the main session. These flows are visible in the UI via task and teammate components, but the execution logic lives lower in services and task runners.

11. The plugin and skills systems are another major extension boundary. `src/plugins/`, `src/services/plugins/`, `src/skills/`, and `src/utils/plugins/` load bundled and external capabilities, validate them, manage marketplace/install flows, and inject commands, tools, hooks, or output styles into the runtime. Skills are content-driven behavior packs, while plugins are a broader extension mechanism with installation, trust, and telemetry concerns.

12. Input modalities and device integrations are layered on top of the core agent loop. `src/voice/`, `src/utils/computerUse/`, `src/utils/claudeInChrome/`, `src/utils/deepLink/`, and `src/utils/terminal.ts` support voice, browser/desktop computer use, protocol handlers, and terminal-specific interactions. The `shims/` and native helper packages exist because some of these integrations depend on native or platform-specific functionality that was not fully recoverable from source maps.

13. The codebase includes a substantial command system built around slash commands and CLI screens. `src/commands/` holds the user-facing command handlers, many implemented as TSX dialogs or flows, while `src/screens/` provides higher-level terminal screens like REPL, resume, and doctor. These commands are how the user reaches settings, onboarding, plugins, MCP, sessions, and maintenance workflows without leaving the terminal app.

14. Overall, the architecture is a layered terminal agent platform: UI/rendering at the top, a shared app state and message model in the middle, and tool/service/remote subsystems underneath. For a diagram, the most important arrows are user input into the command/UI layer, tool and permission decisions through the safety layer, model/API calls through services, and session/task outputs back into the transcript and renderer.

Main entry points: [`src/state/AppState.tsx`](https://github.com/nicole-yi/claude-code-restored/blob/main/src/state/AppState.tsx) (App state), [`src/services`](https://github.com/nicole-yi/claude-code-restored/tree/main/src/services) (API services), [`src/tools`](https://github.com/nicole-yi/claude-code-restored/tree/main/src/tools) (Tool system), [`src/QueryEngine.ts`](https://github.com/nicole-yi/claude-code-restored/blob/main/src/QueryEngine.ts) (Query engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Bootstrap"]
  node_main["CLI entry<br/>bootstrap<br/>[main.tsx]"]
  node_entry["CLI bootstrap<br/>entrypoint<br/>[cli.tsx]"]
  node_setup["Startup setup<br/>init<br/>[setup.ts]"]
  node_state[("App state<br/>store<br/>[AppState.tsx]")]
end

subgraph group_ui["Terminal UI"]
  node_ink["Ink runtime<br/>terminal-ui"]
  node_components["UI components<br/>tsx views"]
  node_commands["Slash commands<br/>command layer"]
end

subgraph group_core["Core Loop"]
  node_input["Input pipeline<br/>input parse"]
  node_history["Conversation history<br/>transcript model<br/>[history.ts]"]
  node_context["Context engine<br/>context mgmt"]
  node_query["Query engine<br/>model orchestration<br/>[QueryEngine.ts]"]
end

subgraph group_execution["Execution"]
  node_tools["Tool system<br/>tool runtime"]
  node_permissions["Permissions<br/>safety layer"]
  node_tasks["Tasks & agents<br/>task runtime"]
end

subgraph group_services["Services"]
  node_services["API services<br/>integration layer"]
  node_mcp["MCP services<br/>mcp runtime"]
  node_compact["Memory & compact<br/>context pruning"]
end

subgraph group_extensions["Extensions"]
  node_extensions["Plugins & skills<br/>extension system"]
end

subgraph group_remote["Remote"]
  node_remotebridge["Remote bridge<br/>network bridge"]
  node_remoteserver["Remote server<br/>session network"]
end

node_main -->|"boots"| node_entry
node_entry -->|"initializes"| node_setup
node_setup -->|"hydrates"| node_state
node_state -->|"drives"| node_ink
node_state -->|"renders"| node_components
node_state -->|"dispatches"| node_commands
node_commands -->|"parses"| node_input
node_input -->|"records"| node_history
node_history -->|"feeds"| node_context
node_context -->|"builds"| node_query
node_query -->|"calls"| node_services
node_query -->|"requests"| node_tools
node_tools -->|"checks"| node_permissions
node_permissions -->|"prompts"| node_components
node_tools -->|"spawns"| node_tasks
node_tasks -->|"reports"| node_history
node_services -->|"compresses"| node_compact
node_services -->|"integrates"| node_mcp
node_services -->|"bridges"| node_remotebridge
node_remotebridge -->|"connects"| node_remoteserver
node_extensions -->|"extends"| node_tools
node_extensions -->|"adds"| node_commands

click node_main "https://github.com/nicole-yi/claude-code-restored/blob/main/src/main.tsx"
click node_entry "https://github.com/nicole-yi/claude-code-restored/blob/main/src/entrypoints/cli.tsx"
click node_setup "https://github.com/nicole-yi/claude-code-restored/blob/main/src/setup.ts"
click node_state "https://github.com/nicole-yi/claude-code-restored/blob/main/src/state/AppState.tsx"
click node_ink "https://github.com/nicole-yi/claude-code-restored/tree/main/src/ink"
click node_components "https://github.com/nicole-yi/claude-code-restored/tree/main/src/components"
click node_commands "https://github.com/nicole-yi/claude-code-restored/tree/main/src/commands"
click node_input "https://github.com/nicole-yi/claude-code-restored/blob/main/src/utils/processUserInput/processUserInput.ts"
click node_history "https://github.com/nicole-yi/claude-code-restored/blob/main/src/history.ts"
click node_context "https://github.com/nicole-yi/claude-code-restored/tree/main/src/query"
click node_query "https://github.com/nicole-yi/claude-code-restored/blob/main/src/QueryEngine.ts"
click node_tools "https://github.com/nicole-yi/claude-code-restored/tree/main/src/tools"
click node_permissions "https://github.com/nicole-yi/claude-code-restored/tree/main/src/hooks/toolPermission"
click node_tasks "https://github.com/nicole-yi/claude-code-restored/tree/main/src/tasks"
click node_services "https://github.com/nicole-yi/claude-code-restored/tree/main/src/services"
click node_mcp "https://github.com/nicole-yi/claude-code-restored/tree/main/src/services/mcp"
click node_compact "https://github.com/nicole-yi/claude-code-restored/tree/main/src/services/compact"
click node_remotebridge "https://github.com/nicole-yi/claude-code-restored/tree/main/src/bridge"
click node_remoteserver "https://github.com/nicole-yi/claude-code-restored/tree/main/src/server"
click node_extensions "https://github.com/nicole-yi/claude-code-restored/tree/main/src/plugins"

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_entry,node_setup,node_state,node_remotebridge,node_remoteserver toneBlue
class node_ink,node_components,node_commands toneAmber
class node_input,node_history,node_context,node_query toneMint
class node_tools,node_permissions,node_tasks toneRose
class node_services,node_mcp,node_compact toneIndigo
class node_extensions toneTeal
```

## Components

### Bootstrap

Startup, configuration, and app state setup

- [CLI entry](https://github.com/nicole-yi/claude-code-restored/blob/main/src/main.tsx): bootstrap · Starts the terminal app and wires top-level runtime entrypoints · `src/main.tsx`
- [CLI bootstrap](https://github.com/nicole-yi/claude-code-restored/blob/main/src/entrypoints/cli.tsx): entrypoint · Command-line entrypoint and runtime initialization · `src/entrypoints/cli.tsx`
- [Startup setup](https://github.com/nicole-yi/claude-code-restored/blob/main/src/setup.ts): init · Loads config, auth, caches, and preflight setup · `src/setup.ts`
- [App state](https://github.com/nicole-yi/claude-code-restored/blob/main/src/state/AppState.tsx): store · Central coordination boundary for session, UI, tools, and services · `src/state/AppState.tsx`

### Terminal UI

Ink renderer, React components, and interaction surfaces

- [Ink runtime](https://github.com/nicole-yi/claude-code-restored/tree/main/src/ink): terminal-ui · Custom terminal rendering, layout, focus, and event handling · `src/ink`
- [UI components](https://github.com/nicole-yi/claude-code-restored/tree/main/src/components): tsx views · Messages, dialogs, prompts, permissions, settings, and task views · `src/components`
- [Slash commands](https://github.com/nicole-yi/claude-code-restored/tree/main/src/commands): command layer · User-facing command handlers and terminal screens · `src/commands`

### Core Loop

Conversation model, query flow, and session coordination

- [Input pipeline](https://github.com/nicole-yi/claude-code-restored/blob/main/src/utils/processUserInput/processUserInput.ts): input parse · Processes text, slash commands, and bash commands into actions · `src/utils/processUserInput/processUserInput.ts`
- [Conversation history](https://github.com/nicole-yi/claude-code-restored/blob/main/src/history.ts): transcript model · Normalizes and persists session messages and discovery history · `src/history.ts`
- [Context engine](https://github.com/nicole-yi/claude-code-restored/tree/main/src/query): context mgmt · Builds model context from transcript, memory, files, and limits · `src/query`
- [Query engine](https://github.com/nicole-yi/claude-code-restored/blob/main/src/QueryEngine.ts): model orchestration · Forms model requests, token budgets, and turn transitions · `src/QueryEngine.ts`

### Execution

Tools, permissions, tasks, and agent orchestration

- [Tool system](https://github.com/nicole-yi/claude-code-restored/tree/main/src/tools): tool runtime · Executes file, shell, web, MCP, task, and agent tools · `src/tools`
- [Permissions](https://github.com/nicole-yi/claude-code-restored/tree/main/src/hooks/toolPermission): safety layer · Decides risky actions and manages denials, modes, and approvals · `src/hooks/toolPermission`
- [Tasks & agents](https://github.com/nicole-yi/claude-code-restored/tree/main/src/tasks): task runtime · Background tasks, teammate agents, workflow execution, and progress display · `src/tasks`

### Services

External integrations and session policies

- [API services](https://github.com/nicole-yi/claude-code-restored/tree/main/src/services): integration layer · Anthropic API, auth, analytics, LSP, compacting, and policy services · `src/services`
- [MCP services](https://github.com/nicole-yi/claude-code-restored/tree/main/src/services/mcp): mcp runtime · MCP clients, auth, channel policy, and connection management · `src/services/mcp`
- [Memory & compact](https://github.com/nicole-yi/claude-code-restored/tree/main/src/services/compact): context pruning · Session compression, memory extraction, and context collapse · `src/services/compact`

### Extensions

Plugins, skills, and bundled capability packs

- [Plugins & skills](https://github.com/nicole-yi/claude-code-restored/tree/main/src/plugins): extension system · Loads bundled and external plugins, commands, hooks, and skills · `src/plugins`

### Remote

Networked control and distributed session support

- [Remote bridge](https://github.com/nicole-yi/claude-code-restored/tree/main/src/bridge): network bridge · Remote control, session ingress, trust, and websocket bridge modes · `src/bridge`
- [Remote server](https://github.com/nicole-yi/claude-code-restored/tree/main/src/server): session network · Direct-connect sessions, remote session manager, SSH, and relay support · `src/server`

## Connections

- CLI entry → CLI bootstrap: boots · Top-level executable starts through the CLI entrypoint
- CLI bootstrap → Startup setup: initializes · Parses startup state and prepares the runtime
- Startup setup → App state: hydrates · Builds the shared app state and persistent session context
- App state → Ink runtime: drives · State changes flow into terminal rendering and focus handling
- App state → UI components: renders · UI state is presented through React/TSX views
- App state → Slash commands: dispatches · Command screens and flows are launched from app state
- Slash commands → Input pipeline: parses · User commands and prompts are converted into actions
- Input pipeline → Conversation history: records · User and assistant events become structured transcript entries
- Conversation history → Context engine: feeds · Transcript and session history populate context selection
- Context engine → Query engine: builds · Context packages are turned into model requests and turns
- Query engine → API services: calls · Model execution relies on API, logging, and runtime services
- Query engine → Tool system: requests · The agent loop issues tool calls as part of model turns
- Tool system → Permissions: checks · Sensitive tools are gated by permission decisions
- Permissions → UI components: prompts · Approvals and denials are surfaced in terminal dialogs
- Tool system → Tasks & agents: spawns · Tools can create background tasks and teammate agents
- Tasks & agents → Conversation history: reports · Task output and progress return into the session transcript
- API services → Memory & compact: compresses · Session memory and context services trim long-running conversations
- API services → MCP services: integrates · External tool servers are managed through MCP services
- API services → Remote bridge: bridges · Networked control and ingress are handled by bridge services
- Remote bridge → Remote server: connects · Bridge mode can hand off to remote session and server support
- Plugins & skills → Tool system: extends · Plugins and skills add or customize available tools and behaviors
- Plugins & skills → Slash commands: adds · Extensions can contribute terminal commands and screens
