How nicole-yi/claude-code-restored works
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: AppState.tsx App state · services API services · tools Tool system · QueryEngine.ts Query engine
Components 20
Bootstrap
Startup, configuration, and app state setup
- CLI entry · Starts the terminal app and wires top-level runtime entrypoints
src/main.tsx - CLI bootstrap · Command-line entrypoint and runtime initialization
src/entrypoints/cli.tsx - Startup setup · Loads config, auth, caches, and preflight setup
src/setup.ts - App state · Central coordination boundary for session, UI, tools, and services
src/state/AppState.tsx
Terminal UI
Ink renderer, React components, and interaction surfaces
- Ink runtime · Custom terminal rendering, layout, focus, and event handling
src/ink - UI components · Messages, dialogs, prompts, permissions, settings, and task views
src/components - Slash commands · User-facing command handlers and terminal screens
src/commands
Core Loop
Conversation model, query flow, and session coordination
- Input pipeline · Processes text, slash commands, and bash commands into actions
src/utils/processUserInput/processUserInput.ts - Conversation history · Normalizes and persists session messages and discovery history
src/history.ts - Context engine · Builds model context from transcript, memory, files, and limits
src/query - Query engine · Forms model requests, token budgets, and turn transitions
src/QueryEngine.ts
Execution
Tools, permissions, tasks, and agent orchestration
- Tool system · Executes file, shell, web, MCP, task, and agent tools
src/tools - Permissions · Decides risky actions and manages denials, modes, and approvals
src/hooks/toolPermission - Tasks & agents · Background tasks, teammate agents, workflow execution, and progress display
src/tasks
Services
External integrations and session policies
- API services · Anthropic API, auth, analytics, LSP, compacting, and policy services
src/services - MCP services · MCP clients, auth, channel policy, and connection management
src/services/mcp - Memory & compact · Session compression, memory extraction, and context collapse
src/services/compact
Extensions
Plugins, skills, and bundled capability packs
- Plugins & skills · Loads bundled and external plugins, commands, hooks, and skills
src/plugins
Remote
Networked control and distributed session support
- Remote bridge · Remote control, session ingress, trust, and websocket bridge modes
src/bridge - Remote server · Direct-connect sessions, remote session manager, SSH, and relay support
src/server
Connections 22
- 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