Configuring ACP-Compatible Agent Backends (Claude Code and Codex CLI) in AutoResearchClaw

AutoResearchClaw supports ACP-compatible CLI agents including Claude Code and OpenAI Codex through the CodeAgentProvider protocol, configured via CliAgentConfig and instantiated through the create_code_agent factory.

AutoResearchClaw isolates code generation behind a provider abstraction that supports both LLM APIs and ACP-compatible CLI tools. This article explains how to configure agent backends like Claude Code and Codex CLI using the CliAgentConfig dataclass and factory methods defined in researchclaw/experiment/code_agent.py and researchclaw/config.py.

How ACP Agent Backends Work in AutoResearchClaw

The system implements three concrete providers behind the CodeAgentProvider protocol. The LlmCodeAgent handles standard API calls, while ClaudeCodeAgent and CodexAgent enable ACP-compatible CLI execution. Both CLI variants inherit from _CliAgentBase, which enforces the ACP output format—specifically the [thinking] and [plan] blocks that Claude Code expects—according to the implementation in researchclaw/experiment/code_agent.py.

The CodeAgentProvider Hierarchy

Supported providers are enumerated in the CLI_AGENT_PROVIDERS whitelist at lines 9-11 of researchclaw/config.py. The factory function create_code_agent (lines 735-760 in researchclaw/experiment/code_agent.py) validates the chosen provider, checks that the binary exists via shutil.which, and returns the appropriate concrete class.

CLI Base Implementation

The _CliAgentBase class centralizes common machinery for CLI backends. It builds prompts using _generate_prompt, _refine_prompt, and _repair_prompt (lines 82-107), runs the subprocess via _run_subprocess (lines 109-146), and harvests results through _build_result (lines 158-176). The base also enforces ACP output formatting, which is parsed by utilities in researchclaw/utils/thinking_tags.py.

Configuring CliAgentConfig for CLI Agents

The CliAgentConfig dataclass defined at lines 24-42 of researchclaw/config.py exposes all tunable parameters:

@dataclass(frozen=True)
class CliAgentConfig:
    provider: str = "llm"          # "llm" | "claude_code" | "codex"

    binary_path: str = ""          # auto-detect via $PATH if empty

    model: str = ""                # optional model override

    max_budget_usd: float = 5.0    # budget for Claude Code

    timeout_sec: int = 600         # overall CLI timeout

    extra_args: tuple[str, ...] = ()  # additional CLI flags

Authentication Requirements

Claude Code requires the ANTHROPIC_AUTH_TOKEN environment variable, with optional ANTHROPIC_BASE_URL overrides. Codex CLI requires OPENAI_API_KEY. These credentials are accessed by the respective agent classes during subprocess invocation.

YAML-Based Configuration

Supply configuration via RCConfig.from_file using the experiment.cli_agent key:

experiment:
  cli_agent:
    provider: claude_code
    binary_path: ""
    model: sonnet
    max_budget_usd: 10.0
    timeout_sec: 900
    extra_args: []

Runtime Execution Flow

When the pipeline reaches Stage 10 (generation) or Stage 13 (refinement), the following execution model applies:

Prompt Construction

The _generate_prompt method constructs ACP-style textual instructions containing [thinking] and [plan] sections. This prompt format is mandatory for Claude Code compatibility and is processed by the base class before subprocess execution.

Subprocess Management

The _run_subprocess method (lines 109-146) spawns the CLI binary in a fresh working directory. It applies a process-group timeout based on CliAgentConfig.timeout_sec and handles cleanup if the process fails or exceeds its budget.

Result Assembly

The _build_result method (lines 158-176) scans the working directory for generated .py files and packages them into a CodeAgentResult object. This result includes file contents and any error messages captured from stderr.

Pipeline Integration

During full experiment runs, the pipeline consumes CliAgentConfig settings for cost tracking. At line 481 of researchclaw/pipeline/runner.py, the system reads max_budget_usd to enforce budget constraints:

cost_budget = getattr(config.experiment.cli_agent, "max_budget_usd", 0.0)

Practical Configuration Examples

Example 1: Switching to Claude Code Programmatically

from researchclaw.config import RCConfig
from researchclaw.experiment.code_agent import create_code_agent
from researchclaw.prompts import PromptManager

config = RCConfig.default()
config.experiment.cli_agent = config.experiment.cli_agent.__class__(
    provider="claude_code",
    binary_path="/usr/local/bin/claude",
    model="opus",
    max_budget_usd=7.5,
    timeout_sec=800,
    extra_args=("--dangerously-skip-permissions",)
)
agent = create_code_agent(config, llm=None, prompts=PromptManager())

Example 2: Codex CLI with Safety Flags

config.experiment.cli_agent.provider = "codex"
config.experiment.cli_agent.extra_args = ("--no-unsafe", "--max-iterations", "2")
agent = create_code_agent(config, llm=None, prompts=PromptManager())

Example 3: Full Generation-Refine Workflow

from pathlib import Path

# Stage 10: Initial generation

result = agent.generate(
    exp_plan="Implement QAOA for MAX-CUT",
    topic="quantum computing",
    metric_key="approximation_ratio",
    pkg_hint="qiskit, numpy",
    compute_budget="4 CPU-hours",
    workdir=Path("/tmp/exp_workspace")
)

# Stage 13: Refinement based on execution

refined = agent.refine(
    current_files=result.files,
    run_summaries=["run 1: ratio=0.82", "run 2: ratio=0.85"],
    metric_key="approximation_ratio",
    metric_direction="maximize",
    topic="quantum computing",
    extra_hints="increase p-layer depth",
    workdir=Path("/tmp/exp_workspace_refine")
)

Summary

• Provider Architecture: AutoResearchClaw uses CodeAgentProvider with concrete implementations ClaudeCodeAgent and CodexAgent inheriting from _CliAgentBase to support ACP-compatible CLIs.
• Configuration: Use CliAgentConfig (defined in researchclaw/config.py lines 24-42) to select providers via the whitelist at lines 9-11 and set budgets/timeouts.
• Authentication: Claude Code requires ANTHROPIC_AUTH_TOKEN; Codex requires OPENAI_API_KEY.
• Execution: The factory create_code_agent (lines 735-760) instantiates agents that generate ACP-formatted prompts (lines 82-107), manage subprocess lifecycles (lines 109-146), and return structured CodeAgentResult objects containing generated Python files.
• Pipeline Integration: Budget enforcement occurs at line 481 of researchclaw/pipeline/runner.py using values from CliAgentConfig.

Frequently Asked Questions

What is the difference between the "llm" provider and CLI agents like Claude Code or Codex?

The "llm" provider uses LlmCodeAgent to call the internal LLM client via standard API requests. The "claude_code" and "codex" providers spawn external subprocesses (claude -p or codex exec) through the _CliAgentBase class, enabling ACP-compatible agent execution with isolated working directories and distinct authentication flows.

How does AutoResearchClaw authenticate with Claude Code?

Authentication relies on the ANTHROPIC_AUTH_TOKEN environment variable, with optional ANTHROPIC_BASE_URL for custom endpoints. The ClaudeCodeAgent inherits this configuration from CliAgentConfig and passes the environment to the subprocess spawned in _run_subprocess (lines 109-146 of researchclaw/experiment/code_agent.py).

What files does the agent return after execution?

The _build_result method (lines 158-176 of researchclaw/experiment/code_agent.py) collects all .py files written to the working directory and packages them into a CodeAgentResult object. This object contains a dictionary mapping filenames to source code strings, along with any captured error messages.

How do I troubleshoot timeout errors when using CLI agents?

Timeout behavior is controlled by the timeout_sec field in CliAgentConfig (default 600 seconds). The _run_subprocess method applies this as a process-group timeout. If your generation tasks require longer execution, increase this value in your YAML configuration or Python config object before invoking create_code_agent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}