feat: add OpenCode engine support as alternative to Codex

- Add forge-engine crate with Engine trait and Codex/OpenCode implementations
- Add EngineKind enum (codex, opencode) in forge-config
- Add --engine flag to run and analyze commands
- Update doctor to validate configured engine
- Rename codex_* fields to engine_* for generic engine support
- Update documentation (README, AGENTS.md)

Author: puppe1990

AGENTS.md

@@ -14,9 +14,22 @@ This document defines engineering guidance for AI/code agents working in this re
 - `crates/forge-cli`: CLI surface (`forge`, `run`, `status`, `monitor`, `sdd`)
 - `crates/forge-core`: loop engine, output analysis, rate limit, circuit breaker
 - `crates/forge-config`: `.forgerc` and env/flag precedence
+- `crates/forge-engine`: Engine trait and implementations (Codex, OpenCode)
 - `crates/forge-monitor`: TUI monitor
 - `crates/forge-types`: shared serializable types
 
+## Engines
+
+Forge supports multiple AI coding engines via the `Engine` trait in `forge-engine`:
+
+- **Codex** (default): OpenAI's Codex CLI
+- **OpenCode**: Open source AI coding agent
+
+To add a new engine:
+1. Implement the `Engine` trait in `forge-engine/src/lib.rs`
+2. Add the engine variant to `EngineKind` in `forge-config/src/lib.rs`
+3. Update `create_engine()` factory function
+
 ## SDD Workflow
 
 When running `forge` with no subcommand, the assistant asks SDD questions and creates a snapshot under:
@@ -62,7 +75,7 @@ Status semantics:
 
 - `run_started_at_epoch`: start of current `forge run`
 - `current_loop_started_at_epoch`: start of current loop command
-- `last_heartbeat_at_epoch`: last real output/stream heartbeat from Codex process
+- `last_heartbeat_at_epoch`: last real output/stream heartbeat from engine process
 - `.runner_pid`: PID of active forge run process (used by monitor to detect stale `running` state)
 
 ## Config Precedence
@@ -74,11 +87,12 @@ Always preserve precedence:
 3. `.forgerc`
 4. Defaults
 
-Codex runtime global flags can be passed via:
+Engine runtime flags can be passed via:
 
-- `forge run --codex-arg=<value>` (repeatable)
-- `forge run --full-access` (forces `--sandbox danger-full-access`)
-- `.forgerc` key `codex_pre_args = ["--sandbox", "danger-full-access"]`
+- `forge run --engine <codex|opencode>` (select engine)
+- `forge run --engine-arg=<value>` (repeatable)
+- `forge run --full-access` (forces sandbox bypass)
+- `.forgerc` key `engine_pre_args = ["--sandbox", "danger-full-access"]`
 
 Monitor tuning:
 
@@ -103,6 +117,7 @@ cargo test --workspace
 
 - Add or update contract tests in `crates/forge-cli/tests/`
 - Add core behavior tests in `crates/forge-core/tests/`
+- Add engine tests in `crates/forge-engine/src/lib.rs`
 - Validate `fmt`, `clippy`, and `test` before proposing changes
 
 ## Documentation Sync
@@ -117,6 +132,7 @@ When changing user-facing behavior, update at least:
 
 - Use `forge` naming only
 - Do not introduce legacy `ralph` naming in code, docs, env vars, or output
+- Use `engine` for generic engine references (not `codex` specific)
 
 ## Safety Rules
 

Cargo.lock

@@ -5,12 +5,13 @@ Standalone Rust CLI for autonomous coding loops.
 ## Prerequisites
 
 - Rust stable toolchain
-- Codex CLI installed and available in `PATH`
+- Codex CLI or OpenCode CLI installed and available in `PATH`
 
-Check your Codex installation:
+Check your installation:
 
 ```bash
-codex --version
+codex --version   # for Codex engine
+opencode --version # for OpenCode engine
 ```
 
 ## Why
@@ -21,13 +22,34 @@ codex --version
 2. Write plan/spec artifacts.
 3. Execute implementation loop with guarded completion.
 
+## Engines
+
+Forge supports multiple AI coding engines:
+
+- **Codex** (default) - OpenAI's Codex CLI
+- **OpenCode** - Open source AI coding agent
+
+Select the engine via CLI flag:
+
+```bash
+forge run --engine codex    # default
+forge run --engine opencode # use OpenCode
+```
+
+Or configure in `.forgerc`:
+
+```toml
+engine = "opencode"
+```
+
 ## Commands
 
 - `forge` (interactive assistant mode: asks SDD questions, writes plan/specs, then runs loop)
-- `forge run [--full-access] [--thinking off|summary|raw] [--max-loops N] [--timeout-minutes N]`
-- `forge analyze --modified-only`
+- `forge run [--engine codex|opencode] [--full-access] [--thinking off|summary|raw] [--max-loops N] [--timeout-minutes N]`
+- `forge analyze [--engine codex|opencode] --modified-only`
 - `forge status`
 - `forge monitor [--refresh-ms N] [--stall-threshold-secs N]`
+- `forge doctor`
 - `forge sdd list`
 - `forge sdd load <id>`
 
@@ -81,26 +103,21 @@ The runtime state is stored in `.forge/`:
 - `.circuit_breaker_history`
 - `.runner_pid`
 
-## Live visibility (Ralph-style)
+## Live visibility
 
-`forge monitor` now shows, in real time:
+`forge monitor` shows, in real time:
 
 - current loop
 - run timer and current command timer (`HH:MM:SS`)
-- current Codex activity extracted from `.forge/live.log`
+- current engine activity extracted from `.forge/live.log`
 - stalled detection based on heartbeat (`last_heartbeat_at_epoch`)
 - alert when heartbeat is stale (red status panel border and alert line)
 - alert when runner process is missing but status says `running` (stale status)
-- suppressed noise for repeated `codex_core::state_db record_discrepancy` warnings
 
 `forge status` prints `run_timer` and `command_timer`.
 
 `forge run` updates heartbeat (`last_heartbeat_at_epoch`) from real stream events during loop execution.
-If Codex emits no output for 120s, Forge triggers a no-output watchdog and kills that iteration to avoid permanent hangs.
-
-### Monitor screenshot
-
-![Forge monitor live view](docs/assets/forge-monitor-live.png)
+If the engine emits no output for 120s, Forge triggers a no-output watchdog and kills that iteration to avoid permanent hangs.
 
 ## Config precedence
 
@@ -139,12 +156,18 @@ To run against a different folder without changing directories:
 cargo run -p forge -- --cwd /absolute/path/to/project
 ```
 
-To pass native `codex` global flags through `forge run`:
+To use OpenCode instead of Codex:
+
+```bash
+forge --cwd /absolute/path/to/project run --engine opencode
+```
+
+To pass native engine flags through `forge run`:
 
 ```bash
 forge --cwd /absolute/path/to/project run \
-  --codex-arg=--sandbox \
-  --codex-arg=danger-full-access
+  --engine-arg=--sandbox \
+  --engine-arg=danger-full-access
 ```
 
 Shortcut for full sandbox permissions:
@@ -153,7 +176,7 @@ Shortcut for full sandbox permissions:
 forge --cwd /absolute/path/to/project run --full-access
 ```
 
-Control thinking verbosity presets (mapped to Codex `--config` flags):
+Control thinking verbosity presets:
 
 ```bash
 forge --cwd /absolute/path/to/project run --thinking off
@@ -170,8 +193,9 @@ forge --cwd /absolute/path/to/project monitor --stall-threshold-secs 20
 You can also persist these args in `.forgerc`:
 
 ```toml
-codex_pre_args = ["--sandbox", "danger-full-access"]
-thinking_mode = "summary" # off | summary | raw
+engine = "codex"
+engine_pre_args = ["--sandbox", "danger-full-access"]
+thinking_mode = "summary"
 ```
 
 To force a new clean loop session (ignore previous runtime/session artifacts):
@@ -180,7 +204,7 @@ To force a new clean loop session (ignore previous runtime/session artifacts):
 forge --cwd /absolute/path/to/project run --fresh
 ```
 
-`--fresh` clears runtime state files in `.forge/` and adds `--ephemeral` to Codex execution to avoid reusing old sessions.
+`--fresh` clears runtime state files in `.forge/` and adds `--ephemeral` to engine execution to avoid reusing old sessions.
 
 ## Analyze modified files
 
@@ -229,6 +253,19 @@ Fail if any operational warning remains:
 forge --cwd /absolute/path/to/project doctor --strict
 ```
 
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FORGE_ENGINE` | Engine to use (`codex` or `opencode`) |
+| `FORGE_ENGINE_CMD` | Path to engine binary |
+| `FORGE_ENGINE_PRE_ARGS` | Pre-args for engine |
+| `FORGE_ENGINE_EXEC_ARGS` | Exec args for engine |
+| `FORGE_THINKING_MODE` | Thinking mode (`off`, `summary`, `raw`) |
+| `FORGE_MAX_CALLS_PER_HOUR` | Rate limit (default: 100) |
+| `FORGE_TIMEOUT_MINUTES` | Timeout per iteration (default: 15) |
+| `FORGE_RUNTIME_DIR` | Runtime directory (default: `.forge`) |
+
 ## License
 
 MIT. See `LICENSE`.

README.md

@@ -16,6 +16,7 @@ serde.workspace = true
 chrono.workspace = true
 forge-config = { path = "../forge-config" }
 forge-core = { path = "../forge-core" }
+forge-engine = { path = "../forge-engine" }
 forge-monitor = { path = "../forge-monitor" }
 forge-types = { path = "../forge-types" }