The ClaudeCodeAgent is a specialized implementation of the Agent interface designed to orchestrate the Claude Code CLI (@anthropic-ai/claude-code). It manages the agent's lifecycle including Node.js environment bootstrapping via nvm, credential mapping for Anthropic-compatible providers, and parsing session-trace JSONL files to extract rich transcripts and token usage data.
The agent utilizes a multi-stage bootstrap process to ensure a functional Node.js environment exists within the target Runtime before execution.
Before any operation (installation or run), the agent calls ensureNodeRuntime internal/agent/claude_code.go77-79 This function, shared via the CLIAgent infrastructure, ensures:
claude binary is already on the PATH, it exits immediately to save time internal/agent/node_install.go85nvm is missing, it downloads and verifies the installer using a hardcoded SHA256 checksum internal/agent/node_install.go18-20npm_config_prefix to $HOME/.local and ensures $HOME/.local/bin is in the PATH internal/agent/node_install.go67-69The Install method internal/agent/claude_code.go51-70 executes the npm install -g @anthropic-ai/claude-code command. It uses probeAndMergePATH to resolve both $HOME/.local/bin (for the binary) and $HOME/.nvm/current/bin (for the node interpreter) to ensure the shebang line #!/usr/bin/env node works correctly internal/agent/claude_code.go29-33
Claude Code supports the Model Context Protocol (MCP). The agent implements InstallMCP internal/agent/claude_code.go73-81 which registers servers in the project scope. It utilizes the buildClaudeCompatibleMCPInstallCmd helper to generate the specific CLI commands required for Claude's MCP registry, supporting both stdio and http transports internal/agent/mcp.go47-100
Sources: internal/agent/claude_code.go29-95 internal/agent/node_install.go1-98 internal/agent/mcp.go1-100
The Run method internal/agent/claude_code.go110-194 follows a structured pipeline to execute the agent and collect results.
The agent maps credentials to environment variables recognized by the Anthropic SDK:
ANTHROPIC_API_KEY: Standard API key internal/agent/claude_code.go119ANTHROPIC_AUTH_TOKEN: Also set to the API key to support proxies (like anthropic-proxy gateways) that only validate Authorization: Bearer headers internal/agent/claude_code.go126-128ANTHROPIC_BASE_URL: Optional custom endpoint internal/agent/claude_code.go119The agent is executed using the claude CLI with specific flags:
--session-id: A unique UUID generated for the run internal/agent/claude_code.go116-117--settings '{"disableAllHooks":true}': Prevents interactive hooks from interrupting the automated run internal/agent/claude_code_test.go108-110-p --permission-mode=bypassPermissions: Enables non-interactive "print" mode and bypasses confirmation prompts internal/agent/claude_code_test.go111-113--model: Passes the configured model name internal/agent/claude_code_test.go114-116The following diagram illustrates how natural language prompts are transformed into CLI executions and how session data is recovered.
Natural Language to Code Entity Space
Sources: internal/agent/claude_code.go110-157 internal/agent/claude_code_test.go101-120 internal/agent/README.md24-31
Claude Code writes a JSONL trace file for every session. The agent attempts to locate and parse this file to provide a high-fidelity result.
The agent uses findClaudeSessionFile (referenced as findAgentSessionJSONL in shared logic) to locate the trace.
/home/user/repo becomes home-user-repo) internal/agent/README.md25-26~/.claude/projects/<workspaceKey>/*.jsonl using a script executed in the runtime internal/agent/README.md26mtime) internal/agent/README.md26Claude Code provides detailed token metrics in its session logs. The agent captures these during the SessionResult construction via parseSessionFile internal/agent/README.md20-21
input_tokens + cache_read_input_tokens + cache_creation_input_tokens internal/agent/README.md29output_tokens internal/agent/README.md29Sources: internal/agent/README.md16-32 internal/agent/claude_code.go168-172
The agent monitors stdout, stderr, and the parsed session diagnostics for failure signals:
providerAuthFailureSignal which checks for 401/403 related messages internal/agent/claude_code.go201-203providerRateLimitSignal which checks for 429 status codes or "rate limit" strings internal/agent/claude_code.go200The agent integrates with OpenTelemetry if tracing is enabled:
claude_code.session_id and metadata in the span internal/agent/claude_code.go136-138CLAUDE_CODE_ENABLE_TELEMETRY=1 and beta enhanced telemetry flags (CLAUDE_CODE_ENHANCED_TELEMETRY_BETA, ENABLE_ENHANCED_TELEMETRY_BETA) into the agent process environment internal/agent/claude_code.go132-134TRACEPARENT via ContextWithConfiguredAgentSpanAttributes internal/agent/claude_code.go139Claude Code Run Lifecycle
Sources: internal/agent/claude_code.go110-194 internal/agent/README.md22-32 internal/agent/node_install.go79-98
Refresh this wiki