Architecture Overview

​

System Architecture

​

Layer Breakdown

​

1. Entry Layer

• CLI argument parsing via Commander.js
• Initialization and bootstrap
• Command routing
• Session management

• React + Ink terminal UI
• User input handling
• Message rendering
• Status indicators

​

2. Command & Tool Registry

• 50+ slash commands (e.g., /commit, /review, /config)
• Command metadata and handlers
• Permission requirements
• User-facing command interface

• 40+ tool definitions
• Tool schemas (Zod validation)
• Permission models
• Tool execution wrappers

​

3. Core Engine

• Orchestrates the complete agentic loop
• Manages conversation state
• Handles tool execution
• Implements retry logic
• Token budget management
• Context window handling

• Direct API communication
• Streaming response handling
• Error handling and retries
• Usage tracking

​

4. State Management

• UI state (expanded views, selections)
• Tool permission context
• MCP connections
• Tasks and teammates
• Settings

• JSONL transcript format
• Message history
• Tool results
• Session metadata
• Resume capability

• Session ID
• Working directory
• Model configuration
• Cost tracking
• Telemetry state

​

5. API Layer

• Anthropic SDK wrapper
• Message normalization
• Tool schema injection
• Prompt caching
• Streaming implementation

• Direct: Anthropic API (default)
• Bedrock: AWS integration
• Vertex AI: Google Cloud integration

​

6. Tool Execution

​

7. External Integrations

• Connect to external MCP servers
• Tool discovery and invocation
• Resource access
• Authentication handling

• Code intelligence features
• Go-to-definition
• Find references
• Diagnostics

• VS Code extension integration
• JetBrains plugin integration
• Bidirectional communication
• Remote control capabilities

​

8. Context & Prompts

• System prompt builder
• Tool usage instructions
• Model-specific guidance
• Dynamic context injection

• User context (git status, environment)
• System context (OS, shell, capabilities)
• Working directory info

• MEMORY.md file management
• Persistent memory across sessions
• Auto-memory system
• Memory freshness tracking

​

Data Flow

​

User Input → Agent Output

​

Key Design Patterns

​

1. Tool System

// Tool definition structure
{
  name: string,
  description: string,
  inputSchema: ZodSchema,
  execute: async (input, context) => result,
  permissionCheck: (input, context) => decision,
  render: (result) => ReactElement
}

​

2. Permission Model

1. Permission Mode - Global setting (default, plan, auto, bypass)
2. Tool Rules - Per-tool allow/deny rules
3. Runtime Checks - Dynamic permission evaluation

​

3. State Persistence

{"type":"user","content":"...","timestamp":...}
{"type":"assistant","content":"...","timestamp":...}
{"type":"tool_use","name":"...","input":{...},"timestamp":...}
{"type":"tool_result","tool_use_id":"...","content":"...","timestamp":...}

​

4. Streaming Architecture

• Text deltas rendered in real-time
• Tool calls executed as they arrive
• Thinking blocks displayed progressively
• User can interrupt at any time

​

5. Context Management

• Summarization when approaching limits
• Tool result truncation
• Message compaction
• Cache-aware prompt assembly

​

Component Responsibilities

​

QueryEngine Responsibilities

• Orchestrate the agentic loop
• Manage conversation history
• Execute tools with permission checks
• Handle errors and retries
• Track token usage and costs
• Implement thinking mode
• Manage context window

​

AppState Responsibilities

• Store UI state
• Track MCP connections
• Manage tasks and teammates
• Hold permission context
• Cache settings
• Coordinate React renders

​

Tool Responsibilities

• Validate input schemas
• Execute operations safely
• Return structured results
• Render output for display
• Report progress
• Handle errors gracefully

​

MCP Client Responsibilities

• Connect to MCP servers
• Discover tools and resources
• Handle authentication
• Execute remote tools
• Manage server lifecycle
• Report connection status

​

Extensibility Points

​

1. Plugins

• Add new tools
• Register hooks
• Provide MCP servers
• Customize behavior

​

2. Skills

• Markdown-based workflows
• Reusable prompts
• Custom commands
• Conditional activation

​

3. MCP Servers

• External tool providers
• Resource access
• Custom integrations
• Third-party services

​

4. Hooks

• preToolUse - Before tool execution
• postToolUse - After tool execution
• fileEdited - On file changes
• promptSubmit - On user input
• agentStop - On agent completion

​

Performance Optimizations

​

1. Lazy Loading

• React components loaded on demand
• Feature-gated code eliminated at build time
• Dynamic imports for heavy modules

​

2. Caching

• Prompt caching (Anthropic API feature)
• Settings cache
• File state cache
• MCP tool schema cache

​

3. Parallel Execution

• Independent tool calls run in parallel
• MCP server connections established concurrently
• File operations batched when possible

​

4. Streaming

• Incremental response rendering
• Progressive tool execution
• Real-time user feedback

​

Security Architecture

​

Permission System

• Default Mode: Prompt for risky operations
• Plan Mode: More restrictive, requires explicit approval
• Auto Mode: Transcript classifier determines safety
• Bypass Mode: No prompts (dangerous, requires explicit opt-in)

​

Sandboxing

• Shell execution can run directly or through sandbox adapters, depending on mode/configuration
• File operations respect permission rules
• MCP servers run as separate processes
• Bridge connections require authentication

​

Audit Trail

• All tool executions logged
• Session transcripts persisted
• Permission denials recorded
• Cost tracking for accountability

​

Related Links