[Phase 4] Claude Code Engine Adapter

[frankbria]

Summary

Implement an AgentAdapter for Claude Code CLI, allowing CodeFrame to delegate code writing to Claude Code as a subprocess while retaining orchestration control.

Parent issue: #408

Motivation

Claude Code is Anthropic's dedicated coding agent with sophisticated tool use, file editing, and project understanding. Rather than replicating its capabilities in CodeFrame's built-in ReactAgent, delegate to it directly and let CodeFrame handle what it does best: orchestration, verification, and lifecycle management.

Scope

New module: core/engines/claude_code.py

1. ClaudeCodeAdapter implementing AgentAdapter:

class ClaudeCodeAdapter:
    name = "claude-code"
    requires_api_key = {"ANTHROPIC_API_KEY": "Anthropic API key"}
    
    def execute(self, task_prompt, workspace_path, context, timeout_ms):
        # 1. Write task prompt to temp file
        # 2. Launch: claude --print --dangerously-skip-permissions -p <prompt>
        #    with cwd=workspace_path
        # 3. Stream stdout, capture file changes
        # 4. Parse exit code and output into AgentResult
        ...

2. Subprocess management:

   • Launch Claude Code CLI with appropriate flags
   • --print mode for non-interactive output
   • --dangerously-skip-permissions for automated execution (configurable)
   • Set cwd to workspace path
   • Capture stdout/stderr
   • Enforce timeout via timeout_ms

3. Output parsing:

   • Detect file modifications from Claude Code's output
   • Parse success/failure from exit code
   • Extract summary from final output
   • Detect if Claude Code created a blocker-like question

4. Event streaming:

   • Parse Claude Code's streaming output into AgentEvents
   • Forward progress messages to CodeFrame's event system

5. Configuration:

   • claude_code_path: path to Claude Code binary (default: claude)
   • claude_code_flags: additional CLI flags
   • approval_mode: skip (default for automation) or interactive

Key Design Decisions

• Subprocess, not API: Claude Code is a CLI tool, so we launch it as a subprocess. This is the same pattern Symphony uses for Codex.
• Non-interactive by default: For automated batch execution, use --dangerously-skip-permissions. For single-task interactive use, can be configured otherwise.
• File change detection: After Claude Code exits, diff the workspace to detect what changed (using git diff or filesystem timestamps).

Acceptance Criteria

• ClaudeCodeAdapter implements AgentAdapter protocol
• Claude Code launched as subprocess with correct cwd
• Task prompt passed via --print -p flag
• Timeout enforced (process killed after timeout_ms)
• Exit code mapped to AgentResultStatus
• Modified files detected via git diff after execution
• Streaming output forwarded as AgentEvents
• Works with cf work start <id> --execute --engine claude-code
• Integration test with mock Claude Code binary

Dependencies

• Depends on [Phase 4] Agent Adapter Protocol Definition #409 (AgentAdapter protocol)
• Depends on [Phase 4] Task Context Packager for External Agents #410 (context packager for prompt assembly)
• Requires Claude Code CLI installed (claude binary)

[traycerai]

Plan

Observations

The codebase has two existing engines (react and plan) registered in file:codeframe/core/runtime.py's execute_agent() function via a simple if engine == "react": ... else: ... branch. There is no AgentAdapter protocol yet — adding claude-code means extending execute_agent() with a new branch and creating file:codeframe/core/engines/claude_code.py. AgentStatus is defined in file:codeframe/core/agent.py, git diff utilities live in file:codeframe/core/git.py, and the event system lives in file:codeframe/core/events.py. Subprocess execution patterns already exist in file:codeframe/core/executor.py and file:codeframe/core/conductor.py.

Approach

Create the new engine module at file:codeframe/core/engines/claude_code.py containing a ClaudeCodeAdapter class, then wire it into execute_agent() in file:codeframe/core/runtime.py, update the CLI help text in file:codeframe/cli/app.py, and add an AGENT_CLAUDE_CODE_* event type family to file:codeframe/core/events.py. This mirrors the existing react/plan pattern without introducing a formal AgentAdapter protocol (which is a dependency tracked under #409 and not yet present in the codebase).

---

Implementation Steps

1. Create file:codeframe/core/engines/__init__.py

Create the engines package file. Keep it minimal — just a docstring marking this as the engine adapters sub-package.

---

2. Create file:codeframe/core/engines/claude_code.py

This is the main deliverable. The module structure:

ClaudeCodeAdapter
├── __init__(workspace, dry_run, verbose, on_event, output_logger, event_publisher)
├── run(task_id) -> AgentStatus
├── _build_prompt(task_id) -> str
├── _launch_process(prompt, workspace_path, timeout_ms) -> subprocess.Popen
├── _stream_output(proc, task_id) -> tuple[str, str]
├── _detect_modified_files(workspace) -> list[str]
└── _parse_result(returncode, stdout, stderr) -> AgentStatus

Constructor parameters should mirror those of ReactAgent in file:codeframe/core/react_agent.py (lines 93–143): workspace, dry_run, verbose, on_event, output_logger, event_publisher. Also accept:

• claude_code_path: str = "claude" — path to the binary
• claude_code_flags: list[str] = [] — additional CLI flags
• approval_mode: str = "skip" — "skip" uses --dangerously-skip-permissions; "interactive" omits it

run(task_id) should:

1. Load the task from file:codeframe/core/tasks.py via tasks.get(workspace, task_id) to get the task title and description.
2. Load agent preferences using load_preferences(workspace.repo_path) from file:codeframe/core/agents_config.py.
3. Build the prompt string via _build_prompt(task_id).
4. Emit EventType.AGENT_STARTED via events.emit_for_workspace().
5. If dry_run, skip the subprocess and return AgentStatus.COMPLETED.
6. Call _launch_process(), _stream_output(), _detect_modified_files(), _parse_result() in sequence.
7. Emit EventType.AGENT_COMPLETED or AGENT_FAILED depending on result.
8. Return the AgentStatus.

_build_prompt(task_id) should assemble a concise task prompt including: task title, description, workspace path, and any relevant content from the AgentPreferences.raw_content. This is the string passed to claude -p.

_launch_process(prompt, workspace_path, timeout_ms) should:

• Write the prompt to a tempfile.NamedTemporaryFile so that it can be passed via -p "$(cat file)" or piped via stdin; the simplest approach is to pass it directly via -p <prompt> if it fits, otherwise use a temp file and shell substitution.
• Build the argv: [claude_code_path, "--print", *approval_flags, "-p", prompt_text] where approval_flags = ["--dangerously-skip-permissions"] when approval_mode == "skip".
• Launch with subprocess.Popen(argv, cwd=workspace_path, stdout=PIPE, stderr=PIPE, text=True).
• Return the Popen handle.

_stream_output(proc, task_id) should:

• Read lines from proc.stdout in a loop using for line in proc.stdout.
• For each line, write it to output_logger.write(line) (if verbose) and call on_event("claude_code_output", {"line": line}).
• Also emit lightweight EventType.AGENT_ITERATION_STARTED events periodically using events.emit_for_workspace() to keep the event log alive.
• Enforce timeout_ms by wrapping proc.wait(timeout=timeout_ms / 1000) in a try/except subprocess.TimeoutExpired block; on timeout, call proc.kill().
• Collect and return (full_stdout, full_stderr).

_detect_modified_files(workspace) should call git.get_status(workspace) from file:codeframe/core/git.py which already returns GitStatus with modified_files and untracked_files. Combine both lists and return them. Emit EventType.FILES_MODIFIED via events.emit_for_workspace() if any files changed.

_parse_result(returncode, stdout, stderr) should:

returncode	Heuristic	Returns
0	—	AgentStatus.COMPLETED
non-zero	stderr contains human-input-question patterns from HUMAN_INPUT_PATTERNS (importable from file:codeframe/core/blocker_detection.py)	AgentStatus.BLOCKED
non-zero	everything else	AgentStatus.FAILED

For the BLOCKED case, set a BlockerInfo on the returned state (see file:codeframe/core/agent.py lines 185–199 for the BlockerInfo dataclass).

Since run() needs to return an AgentState (not just AgentStatus), the method should construct and return a minimal AgentState(status=..., task_id=task_id) — matching what ReactAgent.run() returns, as wrapped in file:codeframe/core/runtime.py line 689.

---

3. Add Claude Code event types to file:codeframe/core/events.py

Inside the EventType class, add:

AGENT_CLAUDE_CODE_STARTED  = "AGENT_CLAUDE_CODE_STARTED"
AGENT_CLAUDE_CODE_OUTPUT   = "AGENT_CLAUDE_CODE_OUTPUT"
AGENT_CLAUDE_CODE_COMPLETED = "AGENT_CLAUDE_CODE_COMPLETED"
AGENT_CLAUDE_CODE_TIMEOUT  = "AGENT_CLAUDE_CODE_TIMEOUT"

These are used in ClaudeCodeAdapter to emit structured events into the workspace event log.

---

4. Update file:codeframe/core/runtime.py — execute_agent()

Line 628: extend valid_engines:

valid_engines = ("plan", "react", "claude-code")

After the if engine == "react" block (around line 671), add an elif engine == "claude-code": branch that:

1. Skips the ANTHROPIC_API_KEY check (or validates a different env var — Claude Code CLI reads it automatically).
2. Instantiates ClaudeCodeAdapter imported from codeframe.core.engines.claude_code.
3. Calls claude_code_adapter.run(run.task_id) and wraps the returned AgentState.
4. Follows the same complete_run / block_run / fail_run flow as the existing branches.

The claude_code_path, claude_code_flags, and approval_mode parameters can be read from environment variables (CLAUDE_CODE_PATH, CLAUDE_CODE_FLAGS, CLAUDE_CODE_APPROVAL_MODE) using os.getenv() with safe defaults, consistent with how GlobalConfig in file:codeframe/core/config.py handles env-backed settings.

---

5. Update file:codeframe/cli/app.py — work_start command

Line 1996–2000: Update the --engine option's help string to include claude-code:

engine: str = typer.Option(
    "react",
    "--engine",
    help="Agent engine: 'react' (default), 'plan' (legacy), or 'claude-code' (Claude Code CLI subprocess)",
)

Line 2041: Update the pre-execution API key check. Currently require_anthropic_api_key() is always called for --execute. For the claude-code engine, the CLI binary handles key loading, so the check should be skipped (or replaced with a binary-availability check using shutil.which("claude") from the standard library):

if execute:
    if engine == "claude-code":
        # Check that claude binary is available
        import shutil
        if not shutil.which("claude"):
            console.print("[red]Error:[/red] 'claude' binary not found. Install Claude Code CLI first.")
            raise typer.Exit(1)
    else:
        from codeframe.cli.validators import require_anthropic_api_key
        require_anthropic_api_key()

---

6. Add GlobalConfig fields for Claude Code in file:codeframe/core/config.py

Add optional fields to GlobalConfig (which uses pydantic_settings):

claude_code_path: str = Field("claude", alias="CLAUDE_CODE_PATH")
claude_code_flags: str = Field("", alias="CLAUDE_CODE_FLAGS")  # space-separated
claude_code_approval_mode: str = Field("skip", alias="CLAUDE_CODE_APPROVAL_MODE")
claude_code_timeout_ms: int = Field(300000, alias="CLAUDE_CODE_TIMEOUT_MS")  # 5 min default

These are picked up in runtime.execute_agent() via get_global_config() and forwarded to ClaudeCodeAdapter.__init__().

---

Execution Flow

sequenceDiagram
    participant CLI as cf work start --engine claude-code
    participant Runtime as runtime.execute_agent()
    participant Adapter as ClaudeCodeAdapter
    participant Claude as claude CLI subprocess
    participant Git as core/git.py
    participant Events as core/events.py

    CLI->>Runtime: execute_agent(workspace, run, engine="claude-code")
    Runtime->>Adapter: ClaudeCodeAdapter(...).run(task_id)
    Adapter->>Events: emit AGENT_CLAUDE_CODE_STARTED
    Adapter->>Adapter: _build_prompt(task_id)
    Adapter->>Claude: Popen(["claude","--print","--dangerously-skip-permissions","-p",prompt], cwd=workspace)
    loop Stream stdout lines
        Claude-->>Adapter: stdout line
        Adapter->>Events: emit AGENT_CLAUDE_CODE_OUTPUT
        Adapter->>Adapter: output_logger.write(line)
    end
    Claude-->>Adapter: exit code
    Adapter->>Git: get_status(workspace) → modified_files
    Adapter->>Events: emit FILES_MODIFIED (if any)
    Adapter->>Adapter: _parse_result(returncode, stdout, stderr)
    Adapter-->>Runtime: AgentState(status=COMPLETED|FAILED|BLOCKED)
    Runtime->>Runtime: complete_run / fail_run / block_run
    Runtime-->>CLI: AgentState

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has two existing engines (`react` and `plan`) registered in `file:codeframe/core/runtime.py`'s `execute_agent()` function via a simple `if engine == "react": ... else: ...` branch. There is no `AgentAdapter` protocol yet — adding `claude-code` means extending `execute_agent()` with a new branch and creating `file:codeframe/core/engines/claude_code.py`. `AgentStatus` is defined in `file:codeframe/core/agent.py`, git diff utilities live in `file:codeframe/core/git.py`, and the event system lives in `file:codeframe/core/events.py`. Subprocess execution patterns already exist in `file:codeframe/core/executor.py` and `file:codeframe/core/conductor.py`.

## Approach

Create the new engine module at `file:codeframe/core/engines/claude_code.py` containing a `ClaudeCodeAdapter` class, then wire it into `execute_agent()` in `file:codeframe/core/runtime.py`, update the CLI help text in `file:codeframe/cli/app.py`, and add an `AGENT_CLAUDE_CODE_*` event type family to `file:codeframe/core/events.py`. This mirrors the existing `react`/`plan` pattern without introducing a formal `AgentAdapter` protocol (which is a dependency tracked under #409 and not yet present in the codebase).

---

## Implementation Steps

### 1. Create `file:codeframe/core/engines/__init__.py`

Create the `engines` package file. Keep it minimal — just a docstring marking this as the engine adapters sub-package.

---

### 2. Create `file:codeframe/core/engines/claude_code.py`

This is the main deliverable. The module structure:

```
ClaudeCodeAdapter
├── __init__(workspace, dry_run, verbose, on_event, output_logger, event_publisher)
├── run(task_id) -> AgentStatus
├── _build_prompt(task_id) -> str
├── _launch_process(prompt, workspace_path, timeout_ms) -> subprocess.Popen
├── _stream_output(proc, task_id) -> tuple[str, str]
├── _detect_modified_files(workspace) -> list[str]
└── _parse_result(returncode, stdout, stderr) -> AgentStatus
```

**Constructor parameters** should mirror those of `ReactAgent` in `file:codeframe/core/react_agent.py` (lines 93–143): `workspace`, `dry_run`, `verbose`, `on_event`, `output_logger`, `event_publisher`. Also accept:
- `claude_code_path: str = "claude"` — path to the binary
- `claude_code_flags: list[str] = []` — additional CLI flags
- `approval_mode: str = "skip"` — `"skip"` uses `--dangerously-skip-permissions`; `"interactive"` omits it

**`run(task_id)`** should:
1. Load the task from `file:codeframe/core/tasks.py` via `tasks.get(workspace, task_id)` to get the task title and description.
2. Load agent preferences using `load_preferences(workspace.repo_path)` from `file:codeframe/core/agents_config.py`.
3. Build the prompt string via `_build_prompt(task_id)`.
4. Emit `EventType.AGENT_STARTED` via `events.emit_for_workspace()`.
5. If `dry_run`, skip the subprocess and return `AgentStatus.COMPLETED`.
6. Call `_launch_process()`, `_stream_output()`, `_detect_modified_files()`, `_parse_result()` in sequence.
7. Emit `EventType.AGENT_COMPLETED` or `AGENT_FAILED` depending on result.
8. Return the `AgentStatus`.

**`_build_prompt(task_id)`** should assemble a concise task prompt including: task title, description, workspace path, and any relevant content from the `AgentPreferences.raw_content`. This is the string passed to `claude -p`.

**`_launch_process(prompt, workspace_path, timeout_ms)`** should:
- Write the prompt to a `tempfile.NamedTemporaryFile` so that it can be passed via `-p "$(cat file)"` or piped via stdin; the simplest approach is to pass it directly via `-p <prompt>` if it fits, otherwise use a temp file and shell substitution.
- Build the `argv`: `[claude_code_path, "--print", *approval_flags, "-p", prompt_text]` where `approval_flags = ["--dangerously-skip-permissions"]` when `approval_mode == "skip"`.
- Launch with `subprocess.Popen(argv, cwd=workspace_path, stdout=PIPE, stderr=PIPE, text=True)`.
- Return the `Popen` handle.

**`_stream_output(proc, task_id)`** should:
- Read lines from `proc.stdout` in a loop using `for line in proc.stdout`.
- For each line, write it to `output_logger.write(line)` (if verbose) and call `on_event("claude_code_output", {"line": line})`.
- Also emit lightweight `EventType.AGENT_ITERATION_STARTED` events periodically using `events.emit_for_workspace()` to keep the event log alive.
- Enforce `timeout_ms` by wrapping `proc.wait(timeout=timeout_ms / 1000)` in a `try/except subprocess.TimeoutExpired` block; on timeout, call `proc.kill()`.
- Collect and return `(full_stdout, full_stderr)`.

**`_detect_modified_files(workspace)`** should call `git.get_status(workspace)` from `file:codeframe/core/git.py` which already returns `GitStatus` with `modified_files` and `untracked_files`. Combine both lists and return them. Emit `EventType.FILES_MODIFIED` via `events.emit_for_workspace()` if any files changed.

**`_parse_result(returncode, stdout, stderr)`** should:

| `returncode` | Heuristic | Returns |
|---|---|---|
| 0 | — | `AgentStatus.COMPLETED` |
| non-zero | stderr contains human-input-question patterns from `HUMAN_INPUT_PATTERNS` (importable from `file:codeframe/core/blocker_detection.py`) | `AgentStatus.BLOCKED` |
| non-zero | everything else | `AgentStatus.FAILED` |

For the `BLOCKED` case, set a `BlockerInfo` on the returned state (see `file:codeframe/core/agent.py` lines 185–199 for the `BlockerInfo` dataclass).

Since `run()` needs to return an `AgentState` (not just `AgentStatus`), the method should construct and return a minimal `AgentState(status=..., task_id=task_id)` — matching what `ReactAgent.run()` returns, as wrapped in `file:codeframe/core/runtime.py` line 689.

---

### 3. Add Claude Code event types to `file:codeframe/core/events.py`

Inside the `EventType` class, add:
```
AGENT_CLAUDE_CODE_STARTED  = "AGENT_CLAUDE_CODE_STARTED"
AGENT_CLAUDE_CODE_OUTPUT   = "AGENT_CLAUDE_CODE_OUTPUT"
AGENT_CLAUDE_CODE_COMPLETED = "AGENT_CLAUDE_CODE_COMPLETED"
AGENT_CLAUDE_CODE_TIMEOUT  = "AGENT_CLAUDE_CODE_TIMEOUT"
```
These are used in `ClaudeCodeAdapter` to emit structured events into the workspace event log.

---

### 4. Update `file:codeframe/core/runtime.py` — `execute_agent()`

**Line 628**: extend `valid_engines`:
```python
valid_engines = ("plan", "react", "claude-code")
```

**After the `if engine == "react"` block (around line 671)**, add an `elif engine == "claude-code":` branch that:
1. Skips the `ANTHROPIC_API_KEY` check (or validates a different env var — Claude Code CLI reads it automatically).
2. Instantiates `ClaudeCodeAdapter` imported from `codeframe.core.engines.claude_code`.
3. Calls `claude_code_adapter.run(run.task_id)` and wraps the returned `AgentState`.
4. Follows the same `complete_run` / `block_run` / `fail_run` flow as the existing branches.

The `claude_code_path`, `claude_code_flags`, and `approval_mode` parameters can be read from environment variables (`CLAUDE_CODE_PATH`, `CLAUDE_CODE_FLAGS`, `CLAUDE_CODE_APPROVAL_MODE`) using `os.getenv()` with safe defaults, consistent with how `GlobalConfig` in `file:codeframe/core/config.py` handles env-backed settings.

---

### 5. Update `file:codeframe/cli/app.py` — `work_start` command

**Line 1996–2000**: Update the `--engine` option's `help` string to include `claude-code`:
```python
engine: str = typer.Option(
    "react",
    "--engine",
    help="Agent engine: 'react' (default), 'plan' (legacy), or 'claude-code' (Claude Code CLI subprocess)",
)
```

**Line 2041**: Update the pre-execution API key check. Currently `require_anthropic_api_key()` is always called for `--execute`. For the `claude-code` engine, the CLI binary handles key loading, so the check should be skipped (or replaced with a binary-availability check using `shutil.which("claude")` from the standard library):
```python
if execute:
    if engine == "claude-code":
        # Check that claude binary is available
        import shutil
        if not shutil.which("claude"):
            console.print("[red]Error:[/red] 'claude' binary not found. Install Claude Code CLI first.")
            raise typer.Exit(1)
    else:
        from codeframe.cli.validators import require_anthropic_api_key
        require_anthropic_api_key()
```

---

### 6. Add `GlobalConfig` fields for Claude Code in `file:codeframe/core/config.py`

Add optional fields to `GlobalConfig` (which uses `pydantic_settings`):
```python
claude_code_path: str = Field("claude", alias="CLAUDE_CODE_PATH")
claude_code_flags: str = Field("", alias="CLAUDE_CODE_FLAGS")  # space-separated
claude_code_approval_mode: str = Field("skip", alias="CLAUDE_CODE_APPROVAL_MODE")
claude_code_timeout_ms: int = Field(300000, alias="CLAUDE_CODE_TIMEOUT_MS")  # 5 min default
```

These are picked up in `runtime.execute_agent()` via `get_global_config()` and forwarded to `ClaudeCodeAdapter.__init__()`.

---

### Execution Flow

```mermaid
sequenceDiagram
    participant CLI as cf work start --engine claude-code
    participant Runtime as runtime.execute_agent()
    participant Adapter as ClaudeCodeAdapter
    participant Claude as claude CLI subprocess
    participant Git as core/git.py
    participant Events as core/events.py

    CLI->>Runtime: execute_agent(workspace, run, engine="claude-code")
    Runtime->>Adapter: ClaudeCodeAdapter(...).run(task_id)
    Adapter->>Events: emit AGENT_CLAUDE_CODE_STARTED
    Adapter->>Adapter: _build_prompt(task_id)
    Adapter->>Claude: Popen(["claude","--print","--dangerously-skip-permissions","-p",prompt], cwd=workspace)
    loop Stream stdout lines
        Claude-->>Adapter: stdout line
        Adapter->>Events: emit AGENT_CLAUDE_CODE_OUTPUT
        Adapter->>Adapter: output_logger.write(line)
    end
    Claude-->>Adapter: exit code
    Adapter->>Git: get_status(workspace) → modified_files
    Adapter->>Events: emit FILES_MODIFIED (if any)
    Adapter->>Adapter: _parse_result(returncode, stdout, stderr)
    Adapter-->>Runtime: AgentState(status=COMPLETED|FAILED|BLOCKED)
    Runtime->>Runtime: complete_run / fail_run / block_run
    Runtime-->>CLI: AgentState
```

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#1 - Add Claude Code GitHub Workflow [merged]
#30 - Review codebase against Claude SDK functionality [closed]
#125 - Implement WorkerAgent execute_task method [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!