How prassamin/claude-code works
1. Product shape
- This is a terminal-first agentic CLI for Claude Code, not a generic app server.
- The runtime is Bun, and the primary interactive surface is a React-based TUI built on a custom src/ink rendering/runtime layer.
2. Top-level execution path
- The main entrypoint is src/entrypoints/cli.tsx, with other entrypoints for MCP and SDK integration.
- Startup wiring goes through src/main.tsx, src/setup.ts, and app state/bootstrap modules before the UI and agent loop start.
3. UI and rendering boundary
- src/components, src/screens, src/commands, and src/ink form the presentation layer.
- src/ink is a substantial internal terminal UI framework: it handles layout, input events, focus, screen rendering, and terminal semantics, while the rest of the React components implement dialogs, panels, menus, and message views.
4. State and session model
- src/state, src/context, src/history.ts, and src/bootstrap/state.ts hold the persistent in-memory application state.
- This state tracks conversation history, active tasks, selected model, permissions, session metadata, queued messages, and UI overlays.
5. Agent orchestration core
- The heart of the system is the query/assistant loop in src/QueryEngine.ts, src/assistant, src/tasks, and src/tools.
- User input is transformed into prompts/commands, routed into the query engine, executed through tools, and then rendered back as messages, task updates, and status indicators.
6. Tool execution pipeline
- src/tools/* contains the actual capabilities: bash, file read/write/edit, search, LSP, MCP, agent spawning, web fetch/search, task management, plan/worktree mode, and more.
- Most tools have three parts: execution logic, prompt/schema metadata, and a TUI-facing UI.tsx for permission or progress display.
7. Permission and safety boundary
- Tool use is mediated by src/hooks/toolPermission, src/components/permissions, and the permission utilities in src/utils/permissions.
- This is a major architectural boundary: tool requests are classified, may be approved/denied/routed to dialogs, and are further constrained by sandbox/read-only/path/danger checks before execution.
8. External API / cloud dependency layer
- src/services/api, src/services/oauth, src/services/analytics, and related service modules encapsulate all external network interactions.
- These include Anthropic API calls, usage/rate-limit reporting, OAuth flows, analytics/telemetry, prompt caching, and product-level service endpoints.
9. Remote session and bridge subsystem
- src/bridge, src/remote, src/server, and src/upstreamproxy implement remote control and session ingress/egress paths.
- This layer handles WebSocket/SSE-style transport, session resume, remote permissions, REPL/bridge modes, and direct-connect style session management.
10. MCP and plugin ecosystem
- src/services/mcp, src/commands/mcp, src/components/mcp, and src/plugins implement Model Context Protocol support and plugin loading/management.
- The architecture supports both local and remote MCP servers, plugin marketplaces, plugin trust/validation, and runtime discovery of plugin-provided commands, tools, hooks, and output styles.
11. Background capabilities and “assistant-adjacent” subsystems
- src/services/compact, src/services/memory, src/services/autoDream, src/services/lsp, src/services/voice, and src/services/tips are background services that augment the main agent loop.
- These subsystems handle summarization/compaction, memory extraction and sync, automated dreaming/consolidation, language-server integration, speech/voice, and user guidance/tips.
12. Task and multi-agent model
- src/tasks, src/components/tasks, src/tools/AgentTool, and swarm-related utilities support multiple task types and nested agents.
- The system distinguishes local shell tasks, local/remote agent tasks, in-process teammates, and background/remote sessions; UI components surface their progress and results in a unified task list.
13. Configuration, settings, and persistence
- src/utils/settings, src/services/settingsSync, src/services/remoteManagedSettings, src/utils/secureStorage, and src/memdir manage user/org settings and local persisted state.
- There are clear boundaries between user-editable config, managed/remote config, secure secrets, session storage, memory files, and cached indices.
14. Platform and environment integration
- The repo contains substantial terminal/shell integration (src/utils/shell, src/utils/bash, src/utils/powershell), worktree/git helpers, sandbox/computer-use support, and native shims under src/native-ts.
- This is a local automation product first: it must safely interact with the host shell, filesystem, IDE, and optionally browser/computer-use integrations.
15. Operational concerns
- Telemetry, rate limits, profiling, error logging, and diagnostics are first-class via src/services/analytics, src/utils/telemetry, src/utils/diagLogs, src/services/rateLimitMessages, and src/components/doctor.
- The architecture is built to keep the core loop responsive while asynchronous background watchers, network calls, and task updates feed back into the TUI.
16. Important diagram boundary
- The most accurate high-level diagram is: terminal UI + command layer feeding a central stateful agent loop, which fans out to tool execution/safety, background services, and external cloud/remote integrations, with results flowing back into message history and task UI.
Main entry points: QueryEngine.ts Query engine · state State store · App.tsx App shell · tools Tool hub
Components 21
Entry & runtime
CLI entrypoints, startup wiring, and runtime bootstrap.
Terminal UI
React TUI layer and the internal Ink rendering/runtime framework.
- App shell · Top-level React application composition for the terminal UI.
src/components/App.tsx - Ink core · Custom terminal rendering, layout, focus, events, and screen semantics.
src/ink - Screens · Dedicated screen-level views such as REPL, doctor, and resume flows.
src/screens - Panels · Dialogs, message views, prompts, task panels, permissions, and other React components.
src/components
Agent core
Stateful conversation loop, sessions, tasks, and tool orchestration.
- State store · Central in-memory app state, selectors, and state transitions.
src/state - History · Conversation history and session transcript model.
src/history.ts - Query engine · Main assistant/query loop that turns input into model turns and tool actions.
src/QueryEngine.ts - Assistants · Assistant/session orchestration and task lifecycle coordination.
src/assistant - Tasks · Task definitions, task execution states, and task-specific UI coordination.
src/tasks
Tools
Capability implementations exposed to the agent.
- Tool hub · Tool registry and shared tool abstractions connecting the agent loop to capabilities.
src/tools - File & shell · Bash, PowerShell, file read/write/edit, search, and LSP-style local code tools.
src/tools/BashTool - Agent & MCP · Subagent spawning, MCP resources, workflow tools, and plugin-facing capabilities.
src/tools/AgentTool
Safety & permissions
Approval, sandbox, path, and destructive-action boundaries.
- Permissions · Tool classification, user approval, and permission routing.
src/hooks/toolPermission - Sandbox checks · Read-only, path, filesystem, and destructive-command validation utilities.
src/utils/permissions
Integrations
Cloud APIs, MCP, remote bridge, plugins, and background services.
- API services · Anthropic API, usage, analytics, OAuth, and product service calls.
src/services/api - Remote bridge · Remote session ingress/egress, bridge modes, and session resume plumbing.
src/bridge - MCP & plugins · MCP server management, plugin discovery, trust, validation, and runtime loading.
src/services/mcp - Background svc · Compaction, memory, auto-dream, LSP, voice, and tip-generation services.
src/services/compact
Platform
Local shell, filesystem, git, native, and environment integration.
- Platform · Shell, git, worktree, sandbox, native shims, and host-environment integration.
src/utils
Connections 24
- CLI entry → Bootstrap: boot · Launches startup wiring and application setup.
- Bootstrap → App shell: mounts · Creates the top-level app shell after initialization.
- App shell → Ink core: renders via · The app is rendered through the custom terminal runtime.
- App shell → Screens: navigates · Routes to dedicated screens and modal flows.
- App shell → Panels: composes · Builds the interactive presentation layer from reusable components.
- Panels → State store: reads/writes · UI reacts to and mutates application state.
- Screens → State store: binds · Screen flows operate on the same session state.
- State store → History: persists · Conversation turns and session metadata are tracked in history.
- State store → Query engine: drives · State changes trigger the main assistant loop.
- Query engine → Assistants: orchestrates · The engine delegates session and assistant lifecycle work.
- Assistants → Tasks: spawns · Assistant work is represented as tasks.
- Query engine → Tool hub: invokes · Model turns request tools through the shared tool layer.
- Tool hub → File & shell: includes · Local file, shell, and code-analysis tools.
- Tool hub → Agent & MCP: includes · Agent spawning, workflow, and MCP-facing tools.
- Tool hub → Permissions: checked by · Tool requests pass through permission mediation.
- Permissions → Sandbox checks: enforces · Permission decisions are constrained by sandbox and safety policy.
- File & shell → Platform: uses · Executes through host shell, filesystem, git, and native helpers.
- Agent & MCP → MCP & plugins: extends · Can surface plugin and MCP-provided functionality.
- Query engine → Background svc: augments · Summarization, memory, LSP, voice, and tips feed the loop.
- Query engine → API services: calls · Model and product requests go through external service clients.
- Query engine → Remote bridge: syncs · Remote sessions and bridge ingress/egress connect to the loop.
- API services → MCP & plugins: supports · Cloud-backed service access and remote MCP management coexist.
- Remote bridge → Tasks: streams · Remote activity is surfaced as tasks and session progress.
- Background svc → State store: updates · Background work feeds state, overlays, and status indicators.