# thjyneg/claude-code-rev architecture

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

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

## Overview

1. This is a terminal-first Claude Code client, not a web app. The runtime is TypeScript on Bun, with a custom Ink-based terminal UI under `src/ink` and React components under `src/components` to render the interactive experience.

2. The top-level application flow starts in `src/main.tsx`, `src/bootstrap-entry.ts`, and `src/dev-entry.ts`, then fans into the CLI entrypoints in `src/entrypoints` and the command registry in `src/commands.ts`. The CLI command tree in `src/commands/**` is the primary user-facing surface.

3. The core conversation engine lives around `src/QueryEngine.ts`, `src/Task.ts`, and `src/Tool.ts`. These files represent the central loop: user input becomes a task/query, the model responds, and tool calls are executed and folded back into the session state.

4. Tool execution is a major subsystem. Concrete tools live in `src/tools/**` such as Bash, file read/write/edit, web fetch/search, LSP, MCP, task management, and agent spawning. Shared orchestration and streaming happen in `src/services/tools`, which acts as the execution boundary between model output and side effects.

5. The UI is organized by concern rather than by screen. `src/components/messages`, `src/components/permissions`, `src/components/tasks`, `src/components/PromptInput`, and `src/components/Settings` are the main panes/dialog families. These render model turns, permission prompts, background activity, configuration, and status overlays.

6. State management is centralized in `src/state`, with app-wide state, selectors, and stores feeding both the UI and the tool/query loop. Supporting context providers in `src/context` and `src/components/design-system` make cross-cutting concerns like notifications, overlays, modal state, and theming available across the app.

7. Permissions and safety are first-class boundaries. `src/hooks/toolPermission`, `src/utils/permissions`, and `src/components/permissions/**` implement approval flows, rule matching, denial tracking, and mode selection. Tool handlers consult these layers before running potentially destructive shell, filesystem, or computer-use actions.

8. Session and multi-session coordination are split across several paths: `src/assistant`, `src/history.ts`, `src/remote`, `src/bridge`, `src/server`, `src/ssh`, and `src/tasks`. These modules cover resume/discovery, remote sessions, repl/bridge transport, direct-connect/server coordination, SSH-backed execution, and background task lifecycle.

9. Integrations with Anthropic, plugins, MCP, skills, and LSP are separate subsystems. Network/API access lives in `src/services/api` and `src/services/oauth`; plugin loading/validation in `src/services/plugins` and `src/utils/plugins`; MCP in `src/services/mcp` and `src/components/mcp`; skills in `src/skills` and `src/services/skillSearch`; language tooling in `src/services/lsp` and `src/tools/LSPTool`.

10. The repo also contains substantial platform-specific and degraded-mode compatibility code. The `shims/` directory and `src/native-ts`, plus helpers under `src/utils/computerUse`, `src/utils/claudeInChrome`, and `src/utils/teleport`, stand in for native modules and private integrations that were not fully recoverable. This is important architecturally because some features are restored through fallbacks rather than original native binaries.

11. Persistent behavior is mostly file- and cache-based, not database-driven. Memory, settings, sessions, permissions, plugin metadata, and task output are stored through utilities in `src/utils/*` such as `sessionStorage`, `settings`, `memdir`, `filePersistence`, `cachePaths`, and `secureStorage`.

12. Telemetry, analytics, and operational safeguards are separate cross-cutting layers. `src/services/analytics`, `src/utils/telemetry`, `src/services/internalLogging`, and `src/services/notifier` capture usage, diagnostics, and events, while update, rate-limit, and sleep-prevention code keeps the CLI responsive and within policy.

Main entry points: [`src/services/tools`](https://github.com/thjyneg/claude-code-rev/tree/main/src/services/tools) (Tool exec), [`src/entrypoints/cli.tsx`](https://github.com/thjyneg/claude-code-rev/blob/main/src/entrypoints/cli.tsx) (CLI entry), [`src/QueryEngine.ts`](https://github.com/thjyneg/claude-code-rev/blob/main/src/QueryEngine.ts) (Query engine), [`src/components`](https://github.com/thjyneg/claude-code-rev/tree/main/src/components) (UI panes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & CLI"]
  node_main(("App start<br/>entrypoint<br/>[main.tsx]"))
  node_bootstrap_entry(("Bootstrap<br/>entrypoint<br/>[bootstrap-entry.ts]"))
  node_dev_entry(("Dev entry<br/>entrypoint<br/>[dev-entry.ts]"))
  node_cli_entry["CLI entry<br/>[cli.tsx]"]
  node_commands_registry["Commands<br/>registry<br/>[commands.ts]"]
  node_command_tree["Command tree<br/>commands"]
end

subgraph group_ui["Terminal UI"]
  node_ink_shell["Ink shell<br/>terminal-ui"]
  node_react_ui["UI panes<br/>react-ui"]
end

subgraph group_core["Core Loop"]
  node_query_engine["Query engine<br/>conversation-core<br/>[QueryEngine.ts]"]
  node_task_model["Task model<br/>task-core<br/>[Task.ts]"]
  node_tool_core["Tool core<br/>tool-core<br/>[Tool.ts]"]
  node_tool_exec["Tool exec<br/>tool-orchestration"]
  node_shell_tools["Shell tools<br/>tool-family"]
  node_content_tools["Content tools<br/>tool-family"]
  node_agent_tools["Agent tools<br/>tool-family"]
end

subgraph group_sessions["Sessions & Remote"]
  node_session_net["Session net<br/>session-coordination"]
  node_remote_server["Remote server<br/>session-server"]
end

subgraph group_integrations["Integrations"]
  node_mcp_api["MCP/API<br/>integration"]
end

subgraph group_crosscutting["Cross-cutting"]
  node_app_state[("App state<br/>state-store")]
  node_permissions{{"Permissions<br/>safety"}}
  node_platform_fallbacks["Fallbacks<br/>platform-adapter"]
  node_persistence_telemetry["Persist & telemetry<br/>cross-cutting"]
end

node_main -->|"boot"| node_bootstrap_entry
node_main -->|"dev"| node_dev_entry
node_bootstrap_entry -->|"launch"| node_cli_entry
node_dev_entry -->|"launch"| node_cli_entry
node_cli_entry -->|"register"| node_commands_registry
node_commands_registry -->|"dispatch"| node_command_tree
node_cli_entry -->|"render"| node_ink_shell
node_ink_shell -->|"host"| node_react_ui
node_react_ui -->|"reads/writes"| node_app_state
node_query_engine -->|"creates"| node_task_model
node_query_engine -->|"invokes"| node_tool_core
node_tool_core -->|"executes"| node_tool_exec
node_tool_exec -->|"runs"| node_shell_tools
node_tool_exec -->|"runs"| node_content_tools
node_tool_exec -->|"runs"| node_agent_tools
node_permissions -->|"gates"| node_tool_exec
node_session_net -->|"syncs"| node_remote_server
node_session_net -->|"feeds"| node_query_engine
node_mcp_api -->|"extends"| node_tool_exec
node_persistence_telemetry -->|"stores"| node_app_state
node_persistence_telemetry -->|"observes"| node_query_engine
node_platform_fallbacks -.->|"adapts"| node_shell_tools
node_platform_fallbacks -.->|"adapts"| node_mcp_api
node_react_ui -->|"prompts"| node_permissions
node_command_tree -->|"controls"| node_session_net

click node_main "https://github.com/thjyneg/claude-code-rev/blob/main/src/main.tsx"
click node_bootstrap_entry "https://github.com/thjyneg/claude-code-rev/blob/main/src/bootstrap-entry.ts"
click node_dev_entry "https://github.com/thjyneg/claude-code-rev/blob/main/src/dev-entry.ts"
click node_cli_entry "https://github.com/thjyneg/claude-code-rev/blob/main/src/entrypoints/cli.tsx"
click node_commands_registry "https://github.com/thjyneg/claude-code-rev/blob/main/src/commands.ts"
click node_command_tree "https://github.com/thjyneg/claude-code-rev/tree/main/src/commands"
click node_ink_shell "https://github.com/thjyneg/claude-code-rev/tree/main/src/ink"
click node_react_ui "https://github.com/thjyneg/claude-code-rev/tree/main/src/components"
click node_app_state "https://github.com/thjyneg/claude-code-rev/tree/main/src/state"
click node_permissions "https://github.com/thjyneg/claude-code-rev/tree/main/src/hooks/toolPermission"
click node_query_engine "https://github.com/thjyneg/claude-code-rev/blob/main/src/QueryEngine.ts"
click node_task_model "https://github.com/thjyneg/claude-code-rev/blob/main/src/Task.ts"
click node_tool_core "https://github.com/thjyneg/claude-code-rev/blob/main/src/Tool.ts"
click node_tool_exec "https://github.com/thjyneg/claude-code-rev/tree/main/src/services/tools"
click node_shell_tools "https://github.com/thjyneg/claude-code-rev/tree/main/src/tools/BashTool"
click node_content_tools "https://github.com/thjyneg/claude-code-rev/tree/main/src/tools/FileReadTool"
click node_agent_tools "https://github.com/thjyneg/claude-code-rev/tree/main/src/tools/AgentTool"
click node_session_net "https://github.com/thjyneg/claude-code-rev/tree/main/src/assistant"
click node_remote_server "https://github.com/thjyneg/claude-code-rev/tree/main/src/server"
click node_mcp_api "https://github.com/thjyneg/claude-code-rev/tree/main/src/services/api"
click node_platform_fallbacks "https://github.com/thjyneg/claude-code-rev/tree/main/shims"
click node_persistence_telemetry "https://github.com/thjyneg/claude-code-rev/tree/main/src/utils"

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_bootstrap_entry,node_dev_entry,node_cli_entry,node_commands_registry,node_command_tree toneBlue
class node_ink_shell,node_react_ui toneAmber
class node_query_engine,node_task_model,node_tool_core,node_tool_exec,node_shell_tools,node_content_tools,node_agent_tools toneMint
class node_session_net,node_remote_server toneRose
class node_mcp_api toneIndigo
class node_app_state,node_permissions,node_platform_fallbacks,node_persistence_telemetry toneTeal
```

## Components

### Runtime & CLI

Bun/TypeScript startup, CLI routing, and command surfaces.

- [App start](https://github.com/thjyneg/claude-code-rev/blob/main/src/main.tsx): entrypoint · Primary process entry and bootstrapping. · `src/main.tsx`
- [Bootstrap](https://github.com/thjyneg/claude-code-rev/blob/main/src/bootstrap-entry.ts): entrypoint · Startup bootstrap entrypoints. · `src/bootstrap-entry.ts`
- [Dev entry](https://github.com/thjyneg/claude-code-rev/blob/main/src/dev-entry.ts): entrypoint · Developer-mode entrypoint. · `src/dev-entry.ts`
- [CLI entry](https://github.com/thjyneg/claude-code-rev/blob/main/src/entrypoints/cli.tsx): cli · Command-line entry and transport setup. · `src/entrypoints/cli.tsx`
- [Commands](https://github.com/thjyneg/claude-code-rev/blob/main/src/commands.ts): registry · Top-level command registry and dispatch. · `src/commands.ts`
- [Command tree](https://github.com/thjyneg/claude-code-rev/tree/main/src/commands): commands · User-facing slash-command and CLI command implementations. · `src/commands`

### Terminal UI

Ink shell, React panes, and interactive overlays.

- [Ink shell](https://github.com/thjyneg/claude-code-rev/tree/main/src/ink): terminal-ui · Custom Ink runtime and terminal rendering engine. · `src/ink`
- [UI panes](https://github.com/thjyneg/claude-code-rev/tree/main/src/components): react-ui · Interactive components for messages, prompt, permissions, tasks, and settings. · `src/components`

### Core Loop

Conversation engine, tasks, and tool orchestration.

- [Query engine](https://github.com/thjyneg/claude-code-rev/blob/main/src/QueryEngine.ts): conversation-core · Main conversation/task loop around model responses and tool calls. · `src/QueryEngine.ts`
- [Task model](https://github.com/thjyneg/claude-code-rev/blob/main/src/Task.ts): task-core · Task/session abstractions used by the conversation loop. · `src/Task.ts`
- [Tool core](https://github.com/thjyneg/claude-code-rev/blob/main/src/Tool.ts): tool-core · Shared tool interface and execution contracts. · `src/Tool.ts`
- [Tool exec](https://github.com/thjyneg/claude-code-rev/tree/main/src/services/tools): tool-orchestration · Streaming execution boundary between model output and side effects. · `src/services/tools`
- [Shell tools](https://github.com/thjyneg/claude-code-rev/tree/main/src/tools/BashTool): tool-family · Bash/PowerShell command execution and filesystem editing tools. · `src/tools/BashTool`
- [Content tools](https://github.com/thjyneg/claude-code-rev/tree/main/src/tools/FileReadTool): tool-family · File, grep, glob, notebook, web, and LSP tools. · `src/tools/FileReadTool`
- [Agent tools](https://github.com/thjyneg/claude-code-rev/tree/main/src/tools/AgentTool): tool-family · Subagent, workflow, task, and message tools. · `src/tools/AgentTool`

### Sessions & Remote

Local, remote, SSH, bridge, and resume paths.

- [Session net](https://github.com/thjyneg/claude-code-rev/tree/main/src/assistant): session-coordination · Resume, remote, bridge, SSH, and direct-connect coordination. · `src/assistant`
- [Remote server](https://github.com/thjyneg/claude-code-rev/tree/main/src/server): session-server · Direct-connect server and remote session manager. · `src/server`

### Integrations

API, MCP, plugins, skills, LSP, and computer-use integrations.

- [MCP/API](https://github.com/thjyneg/claude-code-rev/tree/main/src/services/api): integration · Anthropic/API, OAuth, MCP, plugin, and skill integration layers. · `src/services/api`

### Cross-cutting

State, permissions, persistence, telemetry, and platform compatibility.

- [App state](https://github.com/thjyneg/claude-code-rev/tree/main/src/state): state-store · Central app state, selectors, and stores. · `src/state`
- [Permissions](https://github.com/thjyneg/claude-code-rev/tree/main/src/hooks/toolPermission): safety · Approval rules, denial tracking, and permission prompts. · `src/hooks/toolPermission`
- [Fallbacks](https://github.com/thjyneg/claude-code-rev/tree/main/shims): platform-adapter · Native shims and degraded-mode compatibility for private/native integrations. · `shims`
- [Persist & telemetry](https://github.com/thjyneg/claude-code-rev/tree/main/src/utils): cross-cutting · File-backed persistence, analytics, logging, and operational safeguards. · `src/utils`

## Connections

- App start → Bootstrap: boot · Main startup can route into bootstrap initialization.
- App start → Dev entry: dev · Development startup follows a separate entry path.
- Bootstrap → CLI entry: launch · Bootstrap hands off to CLI runtime setup.
- Dev entry → CLI entry: launch · Dev entry also reaches the CLI runtime.
- CLI entry → Commands: register · CLI wires the command registry.
- Commands → Command tree: dispatch · Command registry dispatches into command implementations.
- CLI entry → Ink shell: render · CLI initializes the terminal UI runtime.
- Ink shell → UI panes: host · Ink hosts the React component tree.
- UI panes → App state: reads/writes · UI panes consume and update global app state.
- Query engine → Task model: creates · The conversation loop materializes tasks and queries.
- Query engine → Tool core: invokes · Model responses are translated into tool calls.
- Tool core → Tool exec: executes · Tool contracts are executed through shared orchestration.
- Tool exec → Shell tools: runs · Shell and filesystem tools are a major execution branch.
- Tool exec → Content tools: runs · Read/search/edit and code-assist tools flow through the executor.
- Tool exec → Agent tools: runs · Subagents, tasks, and workflow tools also run through the executor.
- Permissions → Tool exec: gates · Permission policy gates potentially dangerous tool actions.
- Session net → Remote server: syncs · Session coordination spans remote and direct-connect servers.
- Session net → Query engine: feeds · Resume and remote session state feed the main loop.
- MCP/API → Tool exec: extends · MCP, plugins, skills, and API integrations expand available tools and context.
- Persist & telemetry → App state: stores · State is persisted through file/cache-backed utilities.
- Persist & telemetry → Query engine: observes · Telemetry and logging observe session and tool behavior.
- Fallbacks → Shell tools: adapts · Native shims and fallbacks support shell/computer-use paths.
- Fallbacks → MCP/API: adapts · Fallback modules restore missing native/private integration behavior.
- UI panes → Permissions: prompts · Permission dialogs are surfaced in the terminal UI.
- Command tree → Session net: controls · Commands manage resume, bridge, remote, and SSH workflows.