How akjyshah-stack/claude-code-sample works
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: toolOrchestration.ts Tool Exec · QueryEngine.ts Query Engine · App.tsx App UI · ink.tsx Ink Runtime
Components 19
Terminal UI
Ink-based terminal rendering, screens, components, and input handling.
- Ink Runtime · Custom terminal rendering, event dispatch, focus, and layout engine.
src/ink/ink.tsx - App UI · Main terminal screens, message rendering, prompt input, and dialogs.
src/components/App.tsx - Keybindings · Shortcut parsing, resolution, and command invocation.
src/keybindings/KeybindingProviderSetup.tsx
Assistant Core
Prompt/query orchestration, task lifecycle, and session state.
- CLI Bootstrap · Command entrypoints and app bootstrap into the terminal runtime.
src/entrypoints/cli.tsx - Query Engine · Coordinates model calls, prompts, and tool-using turns.
src/QueryEngine.ts - Task System · Local, remote, shell, and teammate task models plus task state transitions.
src/Task.ts - App State · Central state store and selectors for UI, tasks, settings, and session data.
src/state/AppState.tsx - Background Services · Compaction, prompt suggestions, auto-dream, extraction, and other background intelligence.
src/services/autoDream/autoDream.ts
Tools
Tool definitions, execution, and normalization layer.
- Tool Registry · Defines available tools and their shared interfaces.
src/tools.ts - Tool Exec · Streaming tool execution, orchestration, hooks, and result normalization.
src/services/tools/toolOrchestration.ts - Core Tools · Primary file, shell, search, web, and model-facing tools.
src/tools/BashTool/BashTool.tsx - Agent Tools · Sub-agent spawning, teammate coordination, and agent-specific tool behavior.
src/tools/AgentTool/AgentTool.tsx
Policy
Permissions, sandboxing, and safety boundaries.
- Permissions · Permission rules, user prompts, and approval flow for risky actions.
src/utils/permissions/permissions.ts - Sandbox · Sandbox mode helpers, UI, and execution gating.
src/utils/sandbox/sandbox-adapter.ts
Integrations
Remote control, MCP, plugins, and external service bridges.
- Bridge · Terminal-to-external-session bridge, messaging, and direct control plumbing.
src/bridge/bridgeMain.ts - Remote Sessions · Remote session manager, direct-connect flow, and remote permission relay.
src/remote/RemoteSessionManager.ts - MCP & Plugins · MCP transport and plugin discovery, loading, trust, and validation.
src/services/mcp/MCPConnectionManager.tsx - External APIs · 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 · Conversation history, session memory, memdir files, and restoration.
src/assistant/sessionHistory.ts
Connections 24
- 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.