ruvector/docs/research/claude-code-rvsource/03-agent-loop-and-execution-flow.md

Claude Code CLI: Agent Loop and Execution Flow

Entry Points

CLI Entry

The binary boots through Bun's SEA mechanism into a Commander.js-style CLI:

claude [options] [command] [prompt]

Subcommands (24 registered):

• auth, login, logout -- Authentication
• config (list/show/set/defaults) -- Configuration management
• mcp (add-from-claude-desktop, list, serve, status, setup) -- MCP server management
• doctor -- Diagnostics
• update -- Self-update
• agents -- Agent management
• marketplace, plugin -- Plugin/skill management
• remote-control, serve -- Remote/SSE modes
• auto-mode -- Auto permission mode
• setup-token, xaa -- Auth helpers
• critique, reset-project-choices, clear -- Misc utilities

VS Code Extension Entry

extension.js registers VS Code commands and creates a WebView panel. The WebView (webview/index.js) is a React 18.3.1 application that communicates with the extension host via postMessage.

VS Code commands (21 registered):

• claude-vscode.editor.open / openLast / primaryEditor.open
• claude-vscode.window.open
• claude-vscode.createWorktree
• claude-vscode.insertAtMention
• claude-vscode.focus / blur
• claude-vscode.terminal.open.keyboard

Main Loop Architecture

Core Loop Functions

Function	Purpose
mainLoop	Primary conversation loop
mainLoopModel	Model selection for current session
mainLoopModelForSession	Session-level model override
mainLoopModelOverride	CLI/env model override
mainLoopTokens	Token tracking for main loop
processMessagesForTeleportResume	Handle session teleport/resume

Execution Flow

1. CLI Parse / VS Code Activation
     |
2. Configuration Loading
   - User settings (~/.claude/settings.json)
   - Project settings (.claude/settings.json, .claude/settings.local.json)
   - CLAUDE.md files (auto-discovered up directory tree)
   - Environment variables (498+ recognized)
     |
3. Authentication
   - AnthropicApiKeyAuth (API key from env/helper)
   - ConsoleOAuthFlow (Anthropic Console OAuth)
   - BedrockClient (AWS Bedrock)
   - VertexAI (Google Cloud)
   - Foundry (Azure)
     |
4. MCP Server Connection
   - Read .mcp.json, settings, --mcp-config
   - Connect to MCP servers (stdio, SSE, HTTP transports)
   - Discover tools via tools/list
     |
5. Session Init / Resume
   - Create new session or resume existing
   - Load conversation history
   - Apply CLAUDE.md system prompt
     |
6. Main Loop (per turn):
   a. Collect user input (interactive) or read prompt (--print)
   b. Build message array with system prompt + conversation history
   c. Call Anthropic Messages API (streaming)
   d. Process response stream:
      - Text blocks -> render to terminal/UI
      - Thinking blocks -> display if enabled
      - tool_use blocks -> queue for execution
   e. For each tool_use:
      - Check permissions (PreToolUse hooks)
      - Execute tool
      - Run PostToolUse hooks
      - Append tool_result to messages
   f. If model stopped with tool_use (not end_turn):
      - Loop back to step (c) with updated messages
   g. If model stopped with end_turn:
      - Display final response
      - Wait for next user input
     |
7. Context Management
   - Track token usage
   - Auto-compact when context window fills
   - File checkpointing for recovery
     |
8. Session End
   - Run session-end hooks
   - Persist session to disk
   - Cleanup MCP connections

Streaming Architecture

The API response is streamed using Server-Sent Events (SSE):

StreamEvent -> StreamEventBuffer -> StreamHandler -> UI Renderer

Key streaming patterns:

• StreamFriendlyUIEnabled -- Controls rich terminal rendering
• StreamInterval -- Configurable update frequency
• StreamFinished / StreamFinishing -- Completion states
• Partial message chunks available via --include-partial-messages

Conversation Management

• ConversationManager -- Manages conversation state
• ConversationChain -- Message chain/history
• MessageBuffer / MessageBufferTracker -- Buffer management
• MessageByUuid -- Message lookup
• MessageExistInSession -- Deduplication

Slash Commands (39 Built-in)

Interactive commands processed before sending to the API:

Command	Purpose
/compact	Force context compaction
/clear	Clear conversation
/model	Switch model
/effort	Set reasoning effort level
/fast	Toggle fast mode
/permissions	View/edit permission rules
/hooks	View configured hooks
/mcp	MCP server status
/memory	View/edit auto-memory
/status	Session status
/review-pr	PR review workflow
/commit	Commit workflow
/init	Project initialization
/login / /logout	Authentication
/doctor	Run diagnostics
/bug	Report a bug
/cost	Show cost information
/extra-usage	Usage details
/feedback	Submit feedback
/config	Configuration
/skills	List available skills
/agents	Agent management
/tasks	Task/subagent list
/worker	Background workers
/branch	Create feature branch
/teleport	Session teleport
/rewind	Rewind conversation
/resume	Resume session
/loop	Recurring command
/chrome	Chrome integration
/powerup	Power-up features
/deploy	Deployment workflow
/dev	Development mode
/issue	Issue tracker
/metrics	Performance metrics
/dashboard	Dashboard view
/ultrareview	Deep code review
/prompt	Prompt management
/install-github-app	GitHub App setup

Output Modes

--output-format text         # Default: human-readable
--output-format json         # Single JSON result
--output-format stream-json  # Real-time streaming JSON

Input modes:

--input-format text          # Default: plain text prompt
--input-format stream-json   # Real-time streaming JSON input