I used Claude Code to understand the source code of Claude Code:

  1. Tool-Based Action Framework
    - Tools implement a common interface (Tool.ts) with standard methods
    - Central registry in tools.ts manages tool availability and permissions
    - Tools are categorized as read-only or stateful, affecting execution strategy
  2. Agent Orchestration
    - query.ts serves as the orchestration engine that:
        - Identifies tool use requests in Claude's responses
      - Manages permissions and serializes/deserializes tool data
      - Schedules concurrent or serial tool execution based on tool type
      - Feeds tool results back to Claude in a recursive loop
  3. AgentTool Implementation
    - Enables recursive agent capabilities via sub-agent spawning
    - Sub-agents run with controlled permissions (typically read-only)
    - Each agent invocation is stateless and returns a single result
    - Implements progress streaming via async generators
  4. Execution Flow
    - User query → Claude response → Tool use requests → Permission checks
    - Tool execution → Results normalized → Results fed back to Claude
    - Process repeats with Claude potentially using additional tools
  5. Architectural Patterns
    - Async generators for streaming results and maintaining responsiveness
    - Hierarchical permission model controlling tool access
    - Normalized message formats ensuring consistent communication
    - Logging chains for tracking agent activities
    - Context management with optional compression (/compact)