# akjyshah-stack/claude-code-sample architecture

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

- Interactive diagram: https://gitdiagram.com/akjyshah-stack/claude-code-sample
- Repository: https://github.com/akjyshah-stack/claude-code-sample

## Overview

1. This repository is a large TypeScript/React terminal application, centered on an AI coding assistant CLI. The main architectural style is a layered agent runtime: terminal UI on top, orchestration and policy in the middle, and many tool/integration adapters at the bottom.

2. The top-level execution path starts from the CLI entrypoints and bootstrap code, then hydrates application state and launches the Ink-based terminal UI. The UI is mostly in `src/components/`, with `src/screens/` for full-screen flows and `src/ink/` providing the custom terminal rendering/event system the app is built on.

3. Core assistant behavior is driven by the query and task layer: `src/QueryEngine.ts`, `src/Task.ts`, `src/tools.ts`, and `src/task(s)/`. These pieces coordinate prompt handling, model calls, tool invocation, and the lifecycle of user-facing and background tasks.

4. The tool subsystem is one of the main architectural boundaries. Each capability lives as a tool module under `src/tools/` with matching UI/prompt helpers, while `src/services/tools/` and `src/utils/tool*` handle execution, streaming, hooks, schemas, storage, and result formatting. This is where file edits, shell commands, search, web fetch, MCP access, agent spawning, and task operations are normalized into a common interface.

5. Permission and sandboxing are a separate policy layer, not embedded inside individual tools. The app has dedicated permission utilities and UI under `src/components/permissions/`, `src/hooks/toolPermission/`, and `src/utils/permissions/`, plus sandbox helpers under `src/utils/sandbox/` and `src/components/sandbox/`. This boundary controls destructive actions, filesystem access, shell execution, and mode switching.

6. Multi-agent orchestration is a major subsystem. `src/coordinator/`, `src/tasks/`, `src/tools/AgentTool/`, `src/utils/swarm/`, and related task hooks support spawning sub-agents, teammates, remote agents, and in-process agents. The architecture distinguishes between local session work, background shell work, and distributed or remote teammate execution.

7. Remote control and IDE integration are handled by the bridge/remote stack. `src/bridge/` contains the session transport, permissions callbacks, message handling, and REPL bridge logic; `src/remote/` and `src/server/` manage remote sessions and direct-connect flows. This layer is the boundary between the terminal agent runtime and external control surfaces such as IDEs, remote workspaces, and session relays.

8. The repository also treats plugin and MCP support as first-class extension systems. `src/services/mcp/`, `src/components/mcp/`, `src/commands/mcp/`, `src/plugins/`, and `src/utils/plugins/` handle discovery, install/update, trust, validation, and runtime loading. MCP serves as an external capability protocol, while plugins extend commands, tools, hooks, output styles, and agents.

9. Persistent assistant memory and session continuity are handled through dedicated stores and file-based memory directories. `src/assistant/sessionHistory.ts`, `src/history.ts`, `src/memdir/`, `src/utils/session*`, `src/state/`, and `src/services/SessionMemory/` manage conversation history, memory files, session restoration, and durable state across restarts.

10. There is a substantial background-services layer for intelligence and housekeeping. Examples include auto-compaction, memory extraction, prompt suggestions, task scheduling, inbox polling, tip scheduling, and the `autoDream` workflow in `src/services/autoDream/`. These services continuously update long-term context and keep the active session small enough to run efficiently.

11. External integrations are grouped by domain rather than mixed into the UI. Authentication and API access live under `src/services/oauth/`, `src/services/api/`, and `src/utils/auth*`; telemetry and analytics under `src/services/analytics/` and `src/utils/telemetry/`; voice, browser, Chrome, GitHub, LSP, and desktop integrations each have their own service and utility clusters.

12. Configuration, settings, and migrations form another important boundary. `src/utils/settings/`, `src/bootstrap/`, `src/migrations/`, and `src/services/settingsSync/` handle app defaults, version upgrades, managed settings, and sync. This is where startup behavior, product flags, model selection, permissions defaults, and environment-specific policy are resolved.

13. The app is highly event-driven: user input enters through Ink and keybinding layers, gets translated into commands or prompts, flows through task/tool orchestration, may trigger permissions or background services, and then returns as rendered messages, status lines, progress indicators, or task views. The main diagram should show this as a loop between UI, orchestration, execution, and persistent/session state.

14. In short, the main architectural boundaries are: terminal UI/rendering, assistant orchestration, tool execution, permission/sandbox policy, remote/bridge integration, extension systems, and durable memory/session storage. Those are the subsystems that matter most for an accurate architecture diagram.

Main entry points: [`src/services/tools/toolOrchestration.ts`](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/tools/toolOrchestration.ts) (Tool Exec), [`src/QueryEngine.ts`](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/QueryEngine.ts) (Query Engine), [`src/components/App.tsx`](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/components/App.tsx) (App UI), [`src/ink/ink.tsx`](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/ink/ink.tsx) (Ink Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Terminal UI"]
  node_ink_runtime["Ink Runtime<br/>rendering runtime<br/>[ink.tsx]"]
  node_terminal_ui["App UI<br/>react views<br/>[App.tsx]"]
  node_keybindings["Keybindings<br/>input mapping"]
end

subgraph group_core["Assistant Core"]
  node_entrypoints["CLI Bootstrap<br/>entrypoints<br/>[cli.tsx]"]
  node_query_engine["Query Engine<br/>assistant orchestration<br/>[QueryEngine.ts]"]
  node_task_runtime["Task System<br/>task lifecycle<br/>[Task.ts]"]
  node_state_store["App State<br/>session state<br/>[AppState.tsx]"]
  node_background_services["Background Services<br/>housekeeping<br/>[autoDream.ts]"]
end

subgraph group_tools["Tools"]
  node_tool_registry["Tool Registry<br/>tool catalog<br/>[tools.ts]"]
  node_tool_exec["Tool Exec<br/>execution engine"]
  node_file_shell_tools["Core Tools<br/>tool modules<br/>[BashTool.tsx]"]
  node_agent_tools["Agent Tools<br/>[AgentTool.tsx]"]
end

subgraph group_policy["Policy"]
  node_permission_policy["Permissions<br/>policy layer<br/>[permissions.ts]"]
  node_sandbox_policy["Sandbox<br/>safety controls<br/>[sandbox-adapter.ts]"]
end

subgraph group_integration["Integrations"]
  node_bridge_remote["Bridge<br/>session transport<br/>[bridgeMain.ts]"]
  node_remote_sessions["Remote Sessions<br/>remote control"]
  node_mcp_plugins["MCP & Plugins<br/>extensions"]
  node_integrations["External APIs<br/>service adapters<br/>[client.ts]"]
end

subgraph group_memory["Memory"]
  node_memory_store["Memory Store<br/>durable memory<br/>[sessionHistory.ts]"]
end

node_entrypoints -->|"start"| node_ink_runtime
node_entrypoints -->|"hydrate"| node_state_store
node_ink_runtime -->|"render"| node_terminal_ui
node_ink_runtime -->|"input"| node_keybindings
node_terminal_ui -->|"prompt"| node_query_engine
node_keybindings -->|"commands"| node_query_engine
node_query_engine -->|"select tools"| node_tool_registry
node_tool_registry -->|"execute"| node_tool_exec
node_query_engine -->|"spawn tasks"| node_task_runtime
node_task_runtime -->|"update"| node_state_store
node_tool_exec -->|"run"| node_file_shell_tools
node_tool_exec -->|"run"| node_agent_tools
node_tool_exec -->|"check"| node_permission_policy
node_tool_exec -->|"gate"| node_sandbox_policy
node_permission_policy -->|"prompt"| node_terminal_ui
node_sandbox_policy -->|"status"| node_terminal_ui
node_bridge_remote -->|"relay"| node_remote_sessions
node_bridge_remote -->|"callbacks"| node_permission_policy
node_mcp_plugins -->|"extend"| node_tool_exec
node_mcp_plugins -->|"connect"| node_integrations
node_background_services -->|"write"| node_memory_store
node_memory_store -->|"context"| node_query_engine
node_integrations -->|"adapters"| node_tool_exec
node_state_store -->|"view"| node_terminal_ui

click node_entrypoints "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/entrypoints/cli.tsx"
click node_ink_runtime "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/ink/ink.tsx"
click node_terminal_ui "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/components/App.tsx"
click node_keybindings "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/keybindings/KeybindingProviderSetup.tsx"
click node_query_engine "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/QueryEngine.ts"
click node_task_runtime "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/Task.ts"
click node_state_store "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/state/AppState.tsx"
click node_tool_registry "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/tools.ts"
click node_tool_exec "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/tools/toolOrchestration.ts"
click node_file_shell_tools "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/tools/BashTool/BashTool.tsx"
click node_agent_tools "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/tools/AgentTool/AgentTool.tsx"
click node_permission_policy "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/utils/permissions/permissions.ts"
click node_sandbox_policy "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/utils/sandbox/sandbox-adapter.ts"
click node_bridge_remote "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/bridge/bridgeMain.ts"
click node_remote_sessions "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/remote/RemoteSessionManager.ts"
click node_mcp_plugins "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_background_services "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/autoDream/autoDream.ts"
click node_memory_store "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/assistant/sessionHistory.ts"
click node_integrations "https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/api/client.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_ink_runtime,node_terminal_ui,node_keybindings toneBlue
class node_entrypoints,node_query_engine,node_task_runtime,node_state_store,node_background_services toneAmber
class node_tool_registry,node_tool_exec,node_file_shell_tools,node_agent_tools toneMint
class node_permission_policy,node_sandbox_policy toneRose
class node_bridge_remote,node_remote_sessions,node_mcp_plugins,node_integrations toneIndigo
class node_memory_store toneTeal
```

## Components

### Terminal UI

Ink-based terminal rendering, screens, components, and input handling.

- [Ink Runtime](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/ink/ink.tsx): rendering runtime · Custom terminal rendering, event dispatch, focus, and layout engine. · `src/ink/ink.tsx`
- [App UI](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/components/App.tsx): react views · Main terminal screens, message rendering, prompt input, and dialogs. · `src/components/App.tsx`
- [Keybindings](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/keybindings/KeybindingProviderSetup.tsx): input mapping · Shortcut parsing, resolution, and command invocation. · `src/keybindings/KeybindingProviderSetup.tsx`

### Assistant Core

Prompt/query orchestration, task lifecycle, and session state.

- [CLI Bootstrap](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/entrypoints/cli.tsx): entrypoints · Command entrypoints and app bootstrap into the terminal runtime. · `src/entrypoints/cli.tsx`
- [Query Engine](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/QueryEngine.ts): assistant orchestration · Coordinates model calls, prompts, and tool-using turns. · `src/QueryEngine.ts`
- [Task System](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/Task.ts): task lifecycle · Local, remote, shell, and teammate task models plus task state transitions. · `src/Task.ts`
- [App State](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/state/AppState.tsx): session state · Central state store and selectors for UI, tasks, settings, and session data. · `src/state/AppState.tsx`
- [Background Services](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/autoDream/autoDream.ts): housekeeping · Compaction, prompt suggestions, auto-dream, extraction, and other background intelligence. · `src/services/autoDream/autoDream.ts`

### Tools

Tool definitions, execution, and normalization layer.

- [Tool Registry](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/tools.ts): tool catalog · Defines available tools and their shared interfaces. · `src/tools.ts`
- [Tool Exec](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/tools/toolOrchestration.ts): execution engine · Streaming tool execution, orchestration, hooks, and result normalization. · `src/services/tools/toolOrchestration.ts`
- [Core Tools](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/tools/BashTool/BashTool.tsx): tool modules · Primary file, shell, search, web, and model-facing tools. · `src/tools/BashTool/BashTool.tsx`
- [Agent Tools](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/tools/AgentTool/AgentTool.tsx): multi-agent tools · Sub-agent spawning, teammate coordination, and agent-specific tool behavior. · `src/tools/AgentTool/AgentTool.tsx`

### Policy

Permissions, sandboxing, and safety boundaries.

- [Permissions](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/utils/permissions/permissions.ts): policy layer · Permission rules, user prompts, and approval flow for risky actions. · `src/utils/permissions/permissions.ts`
- [Sandbox](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/utils/sandbox/sandbox-adapter.ts): safety controls · Sandbox mode helpers, UI, and execution gating. · `src/utils/sandbox/sandbox-adapter.ts`

### Integrations

Remote control, MCP, plugins, and external service bridges.

- [Bridge](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/bridge/bridgeMain.ts): session transport · Terminal-to-external-session bridge, messaging, and direct control plumbing. · `src/bridge/bridgeMain.ts`
- [Remote Sessions](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/remote/RemoteSessionManager.ts): remote control · Remote session manager, direct-connect flow, and remote permission relay. · `src/remote/RemoteSessionManager.ts`
- [MCP & Plugins](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/mcp/MCPConnectionManager.tsx): extensions · MCP transport and plugin discovery, loading, trust, and validation. · `src/services/mcp/MCPConnectionManager.tsx`
- [External APIs](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/services/api/client.ts): service adapters · OAuth, analytics, API clients, voice, LSP, GitHub, browser, and desktop integrations. · `src/services/api/client.ts`

### Memory

History, durable memory, and session continuity.

- [Memory Store](https://github.com/akjyshah-stack/claude-code-sample/blob/main/src/assistant/sessionHistory.ts): durable memory · Conversation history, session memory, memdir files, and restoration. · `src/assistant/sessionHistory.ts`

## Connections

- CLI Bootstrap → Ink Runtime: start · Bootstrap launches the terminal runtime.
- CLI Bootstrap → App State: hydrate · Startup restores settings and session state.
- Ink Runtime → App UI: render · Ink renders the React terminal interface.
- Ink Runtime → Keybindings: input · Keyboard and terminal events feed command handling.
- App UI → Query Engine: prompt · User input becomes assistant turns and queries.
- Keybindings → Query Engine: commands · Shortcuts dispatch into assistant actions and screens.
- Query Engine → Tool Registry: select tools · The assistant asks for tool capabilities through the registry.
- Tool Registry → Tool Exec: execute · Registered tools are run through the shared executor.
- Query Engine → Task System: spawn tasks · Assistant turns can create background, shell, or agent tasks.
- Task System → App State: update · Task progress and results are persisted into app state.
- Tool Exec → Core Tools: run · Core tools handle file, shell, search, web, and model actions.
- Tool Exec → Agent Tools: run · Agent-oriented tools spawn and coordinate sub-agents.
- Tool Exec → Permissions: check · Sensitive tool actions pass through approval policy.
- Tool Exec → Sandbox: gate · Execution may be constrained by sandbox mode.
- Permissions → App UI: prompt · Approvals and denials are surfaced in the UI.
- Sandbox → App UI: status · Sandbox state is shown to the user.
- Bridge → Remote Sessions: relay · Bridge messages are forwarded to remote session control.
- Bridge → Permissions: callbacks · Remote control can request permission decisions.
- MCP & Plugins → Tool Exec: extend · MCP and plugins add runtime tools and behaviors.
- MCP & Plugins → External APIs: connect · Extension systems integrate with external services and providers.
- Background Services → Memory Store: write · Background jobs extract and compact long-term memory.
- Memory Store → Query Engine: context · Stored history and memory feed future assistant turns.
- External APIs → Tool Exec: adapters · External APIs are invoked through tool and service adapters.
- App State → App UI: view · UI renders from centralized application state.
