claude-code-agent-architecture

name	claude-code-agent-architecture
description	Research repository analyzing Claude Code CLI Agent architecture, tools, telemetry, and internal mechanisms
triggers	["how does claude code agent work internally","analyze claude code architecture","what tools does claude code use","claude code agent system design","understanding coding agent architecture","claude code tool permissions and execution","implement coding agent like claude code","claude code feature flags and telemetry"]

Claude Code Agent Architecture

Skill by ara.so — AI Agent Skills collection.

Overview

sanbuphy/learn-coding-agent is a research repository that reverse-engineers and documents the architecture of Claude Code (the CLI coding agent). It provides deep technical analysis of:

• Core agent loop: How messages, tools, and API calls form the execution cycle
• Tool system: 40+ built-in tools with permission flows
• Telemetry & privacy: What data is collected and how
• Hidden features: Undercover mode, killswitches, remote control
• Architecture patterns: Production-grade harness mechanisms

This is a learning resource for understanding production coding agents, not the actual Claude Code source code.

Installation

# Clone the research repository
git clone https://github.com/sanbuphy/learn-coding-agent.git
cd learn-coding-agent

# Install dependencies (if you want to explore the documented structure)
npm install
# or
bun install

Note: This is a documentation/research project. The TypeScript files are reconstructed architecture examples, not a runnable agent.

Core Agent Loop Pattern

The fundamental agent pattern documented in this research:

// The minimal agent loop
async function agentLoop(userMessage: string, messages: Message[]) {
  messages.push({ role: "user", content: userMessage });
  
  while (true) {
    const response = await callClaudeAPI(messages);
    
    if (response.stop_reason === "tool_use") {
      // Execute tools
      const toolResults = await executeTools(response.content);
      messages.push({ role: "assistant", content: response.content });
      messages.push({ role: "user", content: toolResults });
      // Loop continues
    } else {
      // Return final text response
      return response.content;
    }
  }
}

The 12 Progressive Harness Mechanisms

Claude Code wraps the basic loop with production features:

1. Permission System: User approval for file writes, command execution
2. Streaming: Real-time token streaming with UI updates
3. Concurrency: Parallel tool execution via StreamingToolExecutor
4. Context Compaction: Automatic message history compression
5. Sub-agents: Specialized agents (verification, review, planning)
6. Persistence: Session state saved to disk
7. MCP Integration: Model Context Protocol server support
8. Cost Tracking: Token usage and API cost accumulation
9. Analytics: Telemetry events (OpenTelemetry + Datadog)
10. Remote Control: Feature flags and killswitches from server
11. Error Recovery: Retry logic with exponential backoff
12. Multi-transport: CLI, bridge, SDK interfaces

Tool System Architecture

Built-in Tool Categories

The research documents 40+ tools across categories:

// Tool registry structure
const toolRegistry = {
  // File operations
  "read_file": { category: "file", risk: "low" },
  "write_to_file": { category: "file", risk: "high", requiresPermission: true },
  "list_files": { category: "file", risk: "low" },
  
  // Command execution
  "execute_command": { category: "command", risk: "high", requiresPermission: true },
  "spawn_agent": { category: "agent", risk: "medium" },
  
  // Search & analysis
  "search_files": { category: "search", risk: "low" },
  "list_code_definition_names": { category: "code", risk: "low" },
  
  // Browser control (via MCP)
  "browser_navigate": { category: "browser", risk: "medium" },
  "browser_click": { category: "browser", :  },
  
  
  : { : , :  },
  : { : , :  }
};

Permission Flow

// Permission checking pattern
interface ToolPermission {
  toolName: string;
  approved: boolean;
  autoApprove?: boolean; // User set in config
  risk: "low" | "medium" | "high";
}

async function checkPermission(tool: Tool, args: any): Promise<boolean> {
  // 1. Check auto-approve rules
  if (config.autoApprove?.[tool.name]) {
    return true;
  }
  
  // 2. Low-risk tools auto-approved
  if (tool.risk === "low") {
    return true;
  }
  
  // 3. Show permission dialog
  const approved = await showPermissionDialog({
    tool: tool.name,
    description: tool.description,
    args: sanitizeArgs(args),
    risk: tool.risk
  });
  
  // 4. Log decision
  analytics.track("tool_permission_decision", {
    : tool.,
    approved,
    : 
  });
  
   approved;
}

Tool Execution with Streaming

// StreamingToolExecutor pattern
class StreamingToolExecutor {
  async executeTools(toolCalls: ToolUse[]): Promise<ToolResult[]> {
    const results: ToolResult[] = [];
    
    // Group by parallelizable vs sequential
    const parallel = toolCalls.filter(t => this.canRunInParallel(t));
    const sequential = toolCalls.filter(t => !this.canRunInParallel(t));
    
    // Execute parallel tools concurrently
    if (parallel.length > 0) {
      const parallelResults = await Promise.all(
        parallel.map(tc => this.executeSingleTool(tc))
      );
      results.push(...parallelResults);
    }
    
    // Execute sequential tools one by one
    for (const toolCall of sequential) {
      const result = await this.executeSingleTool(toolCall);
      results.(result);
    }
    
     results;
  }
  
    (: ): <> {
     tool = toolRegistry.(toolCall.);
    
    
     approved =  (tool, toolCall.);
     (!approved) {
       {
        : toolCall.,
        : ,
        : 
      };
    }
    
    
     {
       output =  tool.(toolCall.);
       {
        : toolCall.,
        : output
      };
    }  (error) {
       {
        : toolCall.,
        : error.,
        : 
      };
    }
  }
}

Key Architectural Components

1. Query Engine

// QueryEngine.ts - SDK/headless query lifecycle
class QueryEngine {
  private messages: Message[] = [];
  private state: TaskState;
  
  async runQuery(input: string, options?: QueryOptions): Promise<QueryResult> {
    // Add user message
    this.messages.push({ role: "user", content: input });
    
    // Context compaction if needed
    if (this.shouldCompact()) {
      await this.compactContext();
    }
    
    // Main loop
    while (true) {
      const response = await this.callAPI();
      
      if (response.stop_reason === "tool_use") {
        const toolResults = await this.toolExecutor.executeTools(
          response.content.filter(c => c. === )
        );
        ..({ : , : response. });
        ..({ : , : toolResults });
      }  {
         { : response., : . };
      }
    }
  }
  
    (): <> {
     compactedMessages =  ..(
      .,
      { :  }
    );
    . = compactedMessages;
  }
}

2. MCP Integration

// MCP (Model Context Protocol) server management
interface MCPServer {
  name: string;
  command: string;
  args: string[];
  env?: Record<string, string>;
}

class MCPManager {
  private servers: Map<string, MCPServerInstance> = new Map();
  
  async connectServer(config: MCPServer): Promise<void> {
    const instance = await this.spawn({
      command: config.command,
      args: config.args,
      env: { ...process.env, ...config.env }
    });
    
    // Register tools from server
    const tools = await instance.listTools();
    tools.forEach(tool => {
      toolRegistry.register(`mcp_${config.name}_${tool.name}`, tool);
    });
    
    this..(config., instance);
  }
  
   (: , : , : ): <> {
     server = ..(serverName);
      server.(toolName, args);
  }
}


 mcpConfig = {
  : {
    : {
      : ,
      : [, ]
    },
    : {
      : ,
      : [],
      : {
        : 
      }
    }
  }
};

3. Telemetry System

// Analytics infrastructure
interface AnalyticsEvent {
  event: string;
  properties: Record<string, any>;
  userId?: string;
  sessionId: string;
  timestamp: number;
}

class AnalyticsService {
  private sinks = {
    firstParty: new OpenTelemetryClient(),
    datadog: new DatadogClient()
  };
  
  track(event: string, properties: Record<string, any>): void {
    const payload: AnalyticsEvent = {
      event,
      properties: {
        ...properties,
        // Automatic fingerprinting
        os: process.platform,
        arch: process.arch,
        nodeVersion: process.version,
        appVersion: packageJson.version,
        repoHash: this.getRepoHash(), // SHA256 of git remote URL
      },
      sessionId: .,
      : .()
    };
    
    
    ...(payload);
    ...(payload);
    
    
     (process.. === ) {
      .(payload);
    }
  }
  
  (: , : , : ):  {
    .(, {
      tool,
      : .(args).,
      : .(result).,
      : !result.
    });
  }
}

4. Feature Flags & Remote Control

// Remote settings management
interface RemoteSettings {
  killswitches: {
    disable_bypass_permissions?: boolean;
    disable_fast_mode?: boolean;
    disable_analytics?: boolean;
  };
  modelOverrides?: {
    defaultModel?: string;
    enabledModels?: string[];
  };
  experimentFlags?: Record<string, any>;
}

class SettingsSyncService {
  private pollInterval = 60 * 60 * 1000; // 1 hour
  
  async poll(): Promise<void> {
    const settings = await fetch(
      "https://api.claude.ai/api/claude_code/settings",
      { headers: { Authorization: `Bearer ${this.token}` } }
    ).then(r => r.json());
    
    // Apply killswitches
    if (settings.killswitches?.disable_bypass_permissions) {
      config.bypassPermissions = false;
    }
    
    
     (.(settings)) {
       accepted =  ({
        : ,
        : ,
        : [, ]
      });
      
       (!accepted) {
        process.(); 
      }
    }
    
    
    .(settings.);
  }
}

Common Patterns

Building a Custom Tool

// Tool.ts pattern
import { buildTool } from "./Tool";

const customTool = buildTool({
  name: "analyze_code_quality",
  description: "Analyzes code quality metrics for a given file",
  parameters: {
    type: "object",
    properties: {
      filePath: { type: "string", description: "Path to file" },
      metrics: { 
        type: "array", 
        items: { type: "string" },
        description: "Metrics to analyze (complexity, coverage, etc.)"
      }
    },
    required: ["filePath"]
  },
  
  async execute({ filePath, metrics = ["complexity"] }) {
    // Read file
    const content = await fs.readFile(filePath, "utf-8");
    
    // Run analysis
    const results = await analyzeCode(content, metrics);
    
    // Return structured output
    return {
      file: filePath,
      metrics: results,
      summary: `Analyzed ${metrics.length} metrics for `
    };
  },
  
  
  : ,
  : ,
  : 
});


toolRegistry.(, customTool);

Implementing Sub-agents

// Sub-agent pattern (verification, review, planning)
class SubAgent {
  constructor(
    private role: string,
    private systemPrompt: string
  ) {}
  
  async run(task: string, context: any): Promise<string> {
    const messages = [
      { role: "system", content: this.systemPrompt },
      { role: "user", content: this.formatTask(task, context) }
    ];
    
    const response = await callClaudeAPI({
      messages,
      model: "claude-sonnet-4.0", // Sub-agents use specific models
      max_tokens: 4096
    });
    
    return response.content[0].text;
  }
  
  private formatTask(task: string, context: any): string {
    return `Task: ${task}\n\nContext:\n`;
  }
}


 reviewAgent =  (
  ,
  
);

 reviewResult =  reviewAgent.(
  ,
  { diff, files, description }
);

Context Compaction Strategy

// Adaptive context compaction
class CompactionService {
  async compact(messages: Message[], options: CompactOptions): Promise<Message[]> {
    const totalTokens = this.estimateTokens(messages);
    
    if (totalTokens < options.maxTokens) {
      return messages; // No compaction needed
    }
    
    // Strategy: Keep recent messages, summarize old ones
    const recentMessages = messages.slice(-10); // Keep last 10
    const oldMessages = messages.slice(0, -10);
    
    // Summarize old conversation
    const summary = await this.summarizeMessages(oldMessages);
    
    return [
      { role: "system", content: `Previous conversation summary:\n${summary}` },
      ...recentMessages
    ];
  }
  
  private async summarizeMessages(messages: Message[]): Promise<string> {
    const response = await ({
      : [
        { : , :  }
      ],
      : , 
      : 
    });
    
     response.[].;
  }
}

Configuration

Environment Variables

# API Configuration
ANTHROPIC_API_KEY=sk-ant-xxx  # Required for Claude API

# Analytics Control
OTEL_LOG_TOOL_DETAILS=1       # Enable detailed tool logging (default: 0)
ANALYTICS_ENABLED=true         # Enable telemetry (default: true)

# Feature Flags
ENABLE_FAST_MODE=true          # Enable fast mode (Haiku for simple tasks)
ENABLE_VOICE_MODE=false        # Enable voice input (experimental)
ENABLE_UNDERCOVER_MODE=false   # Hide AI attribution in commits

# MCP Configuration
MCP_SERVER_PATH=/path/to/mcp-servers
MCP_ALLOWED_PATHS=/workspace,/home/user/projects

# Debug
DEBUG=claude:*                 # Enable debug logging
LOG_LEVEL=info                 # Log level (debug|info|warn|error)

Configuration File

// ~/.claude/config.json
{
  "defaultModel": "claude-sonnet-4.0",
  "autoApprove": {
    "read_file": true,
    "list_files": true,
    "search_files": true
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  },
  "maxTokens": 8192,
  "compactionThreshold": 100000,
  "telemetry": {
     
     
  

Research Reports

The repository includes deep-dive reports in 4 languages:

Key Reports

01-telemetry-and-privacy: Documents two analytics sinks (OpenTelemetry + Datadog), environment fingerprinting, and why opt-out isn't exposed in UI.

02-hidden-features-and-codenames: Reveals animal codenames (Capybara, Tengu, Numbat), feature flags using random word pairs, and internal vs external user differences.

03-undercover-mode: Official employees auto-enter mode that instructs the model to hide AI authorship in public repos ("Do not blow your cover").

04-remote-control-and-killswitches: Hourly polling of settings API, blocking dialogs that exit the app on rejection, 6+ killswitches.

05-future-roadmap: Upcoming Numbat model, KAIROS autonomous mode with <tick> heartbeats, voice mode, 17 unreleased tools.

Access reports in docs/[en|ja|ko|zh]/ directories.

Troubleshooting

Understanding Agent Behavior

// Enable verbose logging to see agent decision process
process.env.DEBUG = "claude:*";
process.env.LOG_LEVEL = "debug";

// This will log:
// - API requests/responses
// - Tool execution decisions
// - Permission checks
// - Context compaction triggers

Analyzing Tool Permissions

// Check which tools require permission
const highRiskTools = Array.from(toolRegistry.entries())
  .filter(([_, tool]) => tool.risk === "high")
  .map(([name, _]) => name);

console.log("High-risk tools:", highRiskTools);
// Output: ["write_to_file", "execute_command", "delete_file", ...]

Debugging MCP Connections

// Test MCP server connection
const mcpManager = new MCPManager();

try {
  await mcpManager.connectServer({
    name: "test-server",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-puppeteer"]
  });
  
  const tools = await mcpManager.listTools("test-server");
  console.log("Available MCP tools:", tools);
} catch (error) {
  console.error("MCP connection failed:", error.message);
  // Common issues: command not found, port conflicts, auth failures
}

Inspecting Telemetry Events

# Enable full tool argument logging
export OTEL_LOG_TOOL_DETAILS=1

# Run agent and grep for tool events
claude-code | grep "tool_executed"

# You'll see:
# {"event":"tool_executed","tool":"write_to_file","argsSize":1234,...}

Additional Resources

• Repository: https://github.com/sanbuphy/learn-coding-agent
• Deep Analysis Reports: docs/ directory (EN/JA/KO/ZH)
• Architecture Diagrams: Referenced in research reports
• Related Projects:
  • Model Context Protocol: https://modelcontextprotocol.io
  • Anthropic Claude API: https://docs.anthropic.com

---

Note: This is a research and educational repository. It documents publicly available information about coding agent architecture. For production coding agent development, refer to official Anthropic documentation and Claude API guides.