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

> Easily configure ACP-compatible agent backends like Claude Code and Codex CLI in AutoResearchClaw using CodeAgentProvider. Learn how to set up your coding agents effortlessly.

- Repository: [AIMING Lab/AutoResearchClaw](https://github.com/aiming-lab/AutoResearchClaw)
- Tags: how-to-guide
- Published: 2026-05-28

---

**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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/experiment/code_agent.py) and [`researchclaw/config.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/config.py). The factory function `create_code_agent` (lines 735-760 in [`researchclaw/experiment/code_agent.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/utils/thinking_tags.py).

## Configuring CliAgentConfig for CLI Agents

The `CliAgentConfig` dataclass defined at lines 24-42 of [`researchclaw/config.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/config.py) exposes all tunable parameters:

```python
@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:

```yaml
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/pipeline/runner.py), the system reads `max_budget_usd` to enforce budget constraints:

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

```

## Practical Configuration Examples

### Example 1: Switching to Claude Code Programmatically

```python
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

```python
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

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`.