[4.D.3] CLI flags: --llm-provider and --llm-model on cf work start / batch run

[frankbria]

Parent

Part of #542 — Multi-provider LLM support

Depends on

#544 — env var wiring must work first

What

Add --llm-provider and --llm-model CLI flags so users can select provider and model per-run without setting environment variables.

Files to modify

• codeframe/cli/app.py — add flags to work_start and work_batch_run commands
• codeframe/core/conductor.py — pass provider/model through BatchRun
• codeframe/core/runtime.py — accept provider/model params, pass to get_provider()
• tests/ — CLI integration tests for new flags

Implementation notes

cf work start:

cf work start <task-id> --execute \
  --llm-provider openai \
  --llm-model qwen2.5-coder:7b

cf work batch run:

cf work batch run --all-ready \
  --llm-provider openai \
  --llm-model gpt-4o

Flag defaults: None — falls back to CODEFRAME_LLM_PROVIDER env var, then anthropic.

BatchRun model update: Add llm_provider: str | None = None and llm_model: str | None = None fields to the BatchRun dataclass.

Priority order for provider selection:

1. CLI flag (--llm-provider)
2. Env var (CODEFRAME_LLM_PROVIDER)
3. Default: anthropic

Help text example:

--llm-provider  LLM provider: anthropic, openai (default: anthropic or $CODEFRAME_LLM_PROVIDER)
--llm-model     Model name for the chosen provider (default: provider's recommended model)
                Examples: claude-sonnet-4-5, gpt-4o, qwen2.5-coder:7b, deepseek-coder

Acceptance criteria

• cf work start <id> --execute --llm-provider openai --llm-model gpt-4o works
• cf work batch run --all-ready --llm-provider openai works
• cf --help shows new flags with clear descriptions
• No flags → unchanged Anthropic behavior
• CLI integration tests cover flag parsing and env var fallback

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• work_start in file:codeframe/cli/app.py (line ~2270) already follows the pattern of engine resolution: CLI flag → env var → workspace config → default. The execute_agent call at line ~2414 passes engine through.
• batch_run in file:codeframe/cli/app.py (line ~3574) follows the same engine resolution pattern and calls conductor.start_batch().
• BatchRun dataclass in file:codeframe/core/conductor.py (line ~509) has optional fields with defaults (engine, stall_timeout_s, stall_action, isolation) — the same pattern applies for the new fields.
• _execute_task_subprocess builds a cf work start ... --execute subprocess command, so --llm-provider and --llm-model flags added to work_start will automatically propagate through batch execution.
• execute_agent in file:codeframe/core/runtime.py (line ~649) calls get_provider("anthropic") hardcoded — this is where the provider/model selection must be injected.
• Test patterns for new BatchRun fields are established in file:tests/core/test_react_engine_integration.py and file:tests/core/test_stall_detector.py.

Approach

Mirror the exact pattern used for --engine / --stall-action / --isolation flags: add CLI options → thread through BatchRun fields → pass into execute_agent → pass into get_provider(). The subprocess bridge in _execute_task_subprocess means batch execution automatically inherits the flags once work_start accepts them.

---

Implementation Steps

1. Extend BatchRun dataclass — file:codeframe/core/conductor.py

Add two optional fields with None defaults after the existing isolation field in the BatchRun dataclass:

• llm_provider: Optional[str] = None
• llm_model: Optional[str] = None

2. Thread llm_provider / llm_model through start_batch — file:codeframe/core/conductor.py

• Add llm_provider: Optional[str] = None and llm_model: Optional[str] = None parameters to start_batch().
• Pass them when constructing the BatchRun object inside start_batch.

3. Thread flags into _execute_task_subprocess — file:codeframe/core/conductor.py

• Add llm_provider: Optional[str] = None and llm_model: Optional[str] = None parameters to _execute_task_subprocess.
• When building the cmd list, append --llm-provider <value> and --llm-model <value> when the values are not None.
• Update all call sites of _execute_task_subprocess (_execute_single_task, _execute_group_parallel's inner execute_task, _execute_serial_resume, _execute_retries) to forward batch.llm_provider and batch.llm_model.

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

• Add llm_provider: Optional[str] = None and llm_model: Optional[str] = None parameters to execute_agent.
• Replace the hardcoded get_provider("anthropic") call (line ~649) with a resolution that:
  1. Uses llm_provider if provided (CLI flag)
  2. Falls back to os.getenv("CODEFRAME_LLM_PROVIDER")
  3. Falls back to "anthropic"
• Pass the resolved llm_model (if any) into get_provider() — this assumes get_provider will accept a model kwarg after [4.D.2] Provider factory + env var wiring (get_provider, ModelSelector) #544 lands.

Priority: CLI flag → CODEFRAME_LLM_PROVIDER env var → "anthropic"

5. Add CLI flags to work_start — file:codeframe/cli/app.py

Add two new typer.Option parameters to work_start (after cloud_timeout):

Flag	Type	Default	Help
--llm-provider	Optional[str]	None	LLM provider: anthropic, openai (default: anthropic or $CODEFRAME_LLM_PROVIDER)
--llm-model	Optional[str]	None	Model name for the chosen provider (e.g. claude-sonnet-4-5, gpt-4o, qwen2.5-coder:7b)

In the execute branch, pass llm_provider and llm_model through to runtime.execute_agent(...).

Update the docstring example block to include the new flags.

6. Add CLI flags to batch_run — file:codeframe/cli/app.py

Add the same two typer.Option parameters to batch_run (after cloud_timeout), using the same defaults and help text.

Apply the same resolution pattern as engine (CLI flag → env var → default) for llm_provider:

resolved_provider = llm_provider or os.getenv("CODEFRAME_LLM_PROVIDER") or None

Pass llm_provider=resolved_provider and llm_model=llm_model to conductor.start_batch(...).

Update the docstring example block.

7. Add CLI integration tests — file:tests/core/test_cli_validators.py

Following the existing TestWorkStartValidation class pattern, add a new test class TestLLMProviderFlags with:

• test_work_start_llm_provider_flag_parsed — invoke work start <id> --stub --llm-provider openai and assert exit code 0 (flag is accepted without error; stub mode avoids real execution).
• test_work_start_llm_model_flag_parsed — invoke work start <id> --stub --llm-provider openai --llm-model gpt-4o and assert exit code 0.
• test_work_start_no_flags_uses_anthropic_default — verify that omitting both flags still results in exit code 0 (stub mode), confirming no regression.

8. Add BatchRun field tests — file:tests/core/test_react_engine_integration.py

Following the TestBatchRunEngineField class pattern, add a TestBatchRunLLMFields class:

• test_batch_run_default_llm_provider_is_none — construct a BatchRun without llm_provider/llm_model and assert both are None.
• test_batch_run_accepts_llm_provider — construct with llm_provider="openai" and assert the field is set.
• test_start_batch_accepts_llm_provider_param — use inspect.signature(start_batch) to assert llm_provider and llm_model are in the parameters with None defaults (mirrors test_start_batch_accepts_stall_action in file:tests/core/test_stall_detector.py).

---

Data Flow

sequenceDiagram
    participant User
    participant CLI as app.py (work_start / batch_run)
    participant Conductor as conductor.py (start_batch)
    participant Subprocess as _execute_task_subprocess
    participant Runtime as runtime.py (execute_agent)
    participant LLM as adapters/llm (get_provider)

    User->>CLI: cf work start <id> --execute --llm-provider openai --llm-model gpt-4o
    CLI->>Runtime: execute_agent(..., llm_provider="openai", llm_model="gpt-4o")
    Runtime->>LLM: get_provider("openai", model="gpt-4o")

    User->>CLI: cf work batch run --all-ready --llm-provider openai
    CLI->>Conductor: start_batch(..., llm_provider="openai", llm_model=None)
    Conductor->>Subprocess: _execute_task_subprocess(..., llm_provider="openai")
    Subprocess->>CLI: cf work start <id> --execute --llm-provider openai
    CLI->>Runtime: execute_agent(..., llm_provider="openai", llm_model=None)
    Runtime->>LLM: get_provider("openai")

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `work_start` in `file:codeframe/cli/app.py` (line ~2270) already follows the pattern of `engine` resolution: CLI flag → env var → workspace config → default. The `execute_agent` call at line ~2414 passes `engine` through.
- `batch_run` in `file:codeframe/cli/app.py` (line ~3574) follows the same engine resolution pattern and calls `conductor.start_batch()`.
- `BatchRun` dataclass in `file:codeframe/core/conductor.py` (line ~509) has optional fields with defaults (`engine`, `stall_timeout_s`, `stall_action`, `isolation`) — the same pattern applies for the new fields.
- `_execute_task_subprocess` builds a `cf work start ... --execute` subprocess command, so `--llm-provider` and `--llm-model` flags added to `work_start` will automatically propagate through batch execution.
- `execute_agent` in `file:codeframe/core/runtime.py` (line ~649) calls `get_provider("anthropic")` hardcoded — this is where the provider/model selection must be injected.
- Test patterns for new `BatchRun` fields are established in `file:tests/core/test_react_engine_integration.py` and `file:tests/core/test_stall_detector.py`.

## Approach

Mirror the exact pattern used for `--engine` / `--stall-action` / `--isolation` flags: add CLI options → thread through `BatchRun` fields → pass into `execute_agent` → pass into `get_provider()`. The subprocess bridge in `_execute_task_subprocess` means batch execution automatically inherits the flags once `work_start` accepts them.

---

## Implementation Steps

### 1. Extend `BatchRun` dataclass — `file:codeframe/core/conductor.py`

Add two optional fields with `None` defaults after the existing `isolation` field in the `BatchRun` dataclass:

- `llm_provider: Optional[str] = None`
- `llm_model: Optional[str] = None`

### 2. Thread `llm_provider` / `llm_model` through `start_batch` — `file:codeframe/core/conductor.py`

- Add `llm_provider: Optional[str] = None` and `llm_model: Optional[str] = None` parameters to `start_batch()`.
- Pass them when constructing the `BatchRun` object inside `start_batch`.

### 3. Thread flags into `_execute_task_subprocess` — `file:codeframe/core/conductor.py`

- Add `llm_provider: Optional[str] = None` and `llm_model: Optional[str] = None` parameters to `_execute_task_subprocess`.
- When building the `cmd` list, append `--llm-provider <value>` and `--llm-model <value>` when the values are not `None`.
- Update all call sites of `_execute_task_subprocess` (`_execute_single_task`, `_execute_group_parallel`'s inner `execute_task`, `_execute_serial_resume`, `_execute_retries`) to forward `batch.llm_provider` and `batch.llm_model`.

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

- Add `llm_provider: Optional[str] = None` and `llm_model: Optional[str] = None` parameters to `execute_agent`.
- Replace the hardcoded `get_provider("anthropic")` call (line ~649) with a resolution that:
  1. Uses `llm_provider` if provided (CLI flag)
  2. Falls back to `os.getenv("CODEFRAME_LLM_PROVIDER")`
  3. Falls back to `"anthropic"`
- Pass the resolved `llm_model` (if any) into `get_provider()` — this assumes `get_provider` will accept a `model` kwarg after #544 lands.

```
Priority: CLI flag → CODEFRAME_LLM_PROVIDER env var → "anthropic"
```

### 5. Add CLI flags to `work_start` — `file:codeframe/cli/app.py`

Add two new `typer.Option` parameters to `work_start` (after `cloud_timeout`):

| Flag | Type | Default | Help |
|---|---|---|---|
| `--llm-provider` | `Optional[str]` | `None` | `LLM provider: anthropic, openai (default: anthropic or $CODEFRAME_LLM_PROVIDER)` |
| `--llm-model` | `Optional[str]` | `None` | `Model name for the chosen provider (e.g. claude-sonnet-4-5, gpt-4o, qwen2.5-coder:7b)` |

In the `execute` branch, pass `llm_provider` and `llm_model` through to `runtime.execute_agent(...)`.

Update the docstring example block to include the new flags.

### 6. Add CLI flags to `batch_run` — `file:codeframe/cli/app.py`

Add the same two `typer.Option` parameters to `batch_run` (after `cloud_timeout`), using the same defaults and help text.

Apply the same resolution pattern as `engine` (CLI flag → env var → default) for `llm_provider`:

```
resolved_provider = llm_provider or os.getenv("CODEFRAME_LLM_PROVIDER") or None
```

Pass `llm_provider=resolved_provider` and `llm_model=llm_model` to `conductor.start_batch(...)`.

Update the docstring example block.

### 7. Add CLI integration tests — `file:tests/core/test_cli_validators.py`

Following the existing `TestWorkStartValidation` class pattern, add a new test class `TestLLMProviderFlags` with:

- **`test_work_start_llm_provider_flag_parsed`** — invoke `work start <id> --stub --llm-provider openai` and assert exit code 0 (flag is accepted without error; stub mode avoids real execution).
- **`test_work_start_llm_model_flag_parsed`** — invoke `work start <id> --stub --llm-provider openai --llm-model gpt-4o` and assert exit code 0.
- **`test_work_start_no_flags_uses_anthropic_default`** — verify that omitting both flags still results in exit code 0 (stub mode), confirming no regression.

### 8. Add `BatchRun` field tests — `file:tests/core/test_react_engine_integration.py`

Following the `TestBatchRunEngineField` class pattern, add a `TestBatchRunLLMFields` class:

- **`test_batch_run_default_llm_provider_is_none`** — construct a `BatchRun` without `llm_provider`/`llm_model` and assert both are `None`.
- **`test_batch_run_accepts_llm_provider`** — construct with `llm_provider="openai"` and assert the field is set.
- **`test_start_batch_accepts_llm_provider_param`** — use `inspect.signature(start_batch)` to assert `llm_provider` and `llm_model` are in the parameters with `None` defaults (mirrors `test_start_batch_accepts_stall_action` in `file:tests/core/test_stall_detector.py`).

---

## Data Flow

```mermaid
sequenceDiagram
    participant User
    participant CLI as app.py (work_start / batch_run)
    participant Conductor as conductor.py (start_batch)
    participant Subprocess as _execute_task_subprocess
    participant Runtime as runtime.py (execute_agent)
    participant LLM as adapters/llm (get_provider)

    User->>CLI: cf work start <id> --execute --llm-provider openai --llm-model gpt-4o
    CLI->>Runtime: execute_agent(..., llm_provider="openai", llm_model="gpt-4o")
    Runtime->>LLM: get_provider("openai", model="gpt-4o")

    User->>CLI: cf work batch run --all-ready --llm-provider openai
    CLI->>Conductor: start_batch(..., llm_provider="openai", llm_model=None)
    Conductor->>Subprocess: _execute_task_subprocess(..., llm_provider="openai")
    Subprocess->>CLI: cf work start <id> --execute --llm-provider openai
    CLI->>Runtime: execute_agent(..., llm_provider="openai", llm_model=None)
    Runtime->>LLM: get_provider("openai")
```

---

Execution Information

Branch: main
Commit: f61db8d

---

💡 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.