Support multiple agent CLIs (Claude & Codex)

Introduce an agent abstraction to support Claude and OpenAI Codex CLIs. Added internal/agent providers (ClaudeProvider, CodexProvider), resolution and installation checks (Resolve, CheckInstalled), and tests. Wire provider selection via --agent / --agent-path flags, CHIEF_AGENT env vars, and .chief/config.yaml (agent.provider, agent.cliPath). Propagate the provider into TUI, new, edit, and convert flows; convert and fix-json now run through the provider. Added Codex JSONL parser for the loop output and accompanying tests. Updated config struct, docs (README, installation, configuration, troubleshooting), and various command code to use the provider abstraction. Key new files: internal/agent/*.go, internal/cmd/convert.go, internal/loop/codex_parser*.go and tests; updated main.go, cmd handlers, prd conversion wiring and docs to reflect multi-agent support.

Author: Simon-BEE

README.md

@@ -44,7 +44,17 @@ See the [documentation](https://minicodemonkey.github.io/chief/concepts/how-it-w
 
 ## Requirements
 
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** or **[Codex CLI](https://developers.openai.com/codex/cli/reference)** installed and authenticated
+
+Use Claude by default, or configure Codex in `.chief/config.yaml`:
+
+```yaml
+agent:
+  provider: codex
+  cliPath: /usr/local/bin/codex   # optional
+```
+
+Or run with `chief --agent codex` or set `CHIEF_AGENT=codex`.
 
 ## License
 

cmd/chief/main.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 
 	tea "github.com/charmbracelet/bubbletea"
+	"github.com/minicodemonkey/chief/internal/agent"
 	"github.com/minicodemonkey/chief/internal/cmd"
 	"github.com/minicodemonkey/chief/internal/config"
 	"github.com/minicodemonkey/chief/internal/git"
@@ -26,6 +27,8 @@ type TUIOptions struct {
 	Merge         bool
 	Force         bool
 	NoRetry       bool
+	Agent         string // --agent claude|codex
+	AgentPath     string // --agent-path
 }
 
 func main() {
@@ -147,6 +150,20 @@ func parseTUIFlags() *TUIOptions {
 			opts.Force = true
 		case arg == "--no-retry":
 			opts.NoRetry = true
+		case arg == "--agent":
+			if i+1 < len(os.Args) {
+				i++
+				opts.Agent = os.Args[i]
+			}
+		case strings.HasPrefix(arg, "--agent="):
+			opts.Agent = strings.TrimPrefix(arg, "--agent=")
+		case arg == "--agent-path":
+			if i+1 < len(os.Args) {
+				i++
+				opts.AgentPath = os.Args[i]
+			}
+		case strings.HasPrefix(arg, "--agent-path="):
+			opts.AgentPath = strings.TrimPrefix(arg, "--agent-path=")
 		case arg == "--max-iterations" || arg == "-n":
 			// Next argument should be the number
 			if i+1 < len(os.Args) {
@@ -210,14 +227,36 @@ func parseTUIFlags() *TUIOptions {
 
 func runNew() {
 	opts := cmd.NewOptions{}
-
 	// Parse arguments: chief new [name] [context...]
 	if len(os.Args) > 2 {
 		opts.Name = os.Args[2]
 	}
 	if len(os.Args) > 3 {
 		opts.Context = strings.Join(os.Args[3:], " ")
 	}
+	// Resolve provider (support --agent/--agent-path after "new")
+	cwd, _ := os.Getwd()
+	cfg, _ := config.Load(cwd)
+	flagAgent, flagPath := "", ""
+	for i := 2; i < len(os.Args); i++ {
+		switch os.Args[i] {
+		case "--agent":
+			if i+1 < len(os.Args) {
+				i++
+				flagAgent = os.Args[i]
+			}
+		case "--agent-path":
+			if i+1 < len(os.Args) {
+				i++
+				flagPath = os.Args[i]
+			}
+		}
+	}
+	opts.Provider = agent.Resolve(flagAgent, flagPath, cfg)
+	if err := agent.CheckInstalled(opts.Provider); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
 
 	if err := cmd.RunNew(opts); err != nil {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
@@ -227,22 +266,38 @@ func runNew() {
 
 func runEdit() {
 	opts := cmd.EditOptions{}
-
-	// Parse arguments: chief edit [name] [--merge] [--force]
+	flagAgent, flagPath := "", ""
+	// Parse arguments: chief edit [name] [--merge] [--force] [--agent] [--agent-path]
 	for i := 2; i < len(os.Args); i++ {
 		arg := os.Args[i]
 		switch arg {
 		case "--merge":
 			opts.Merge = true
 		case "--force":
 			opts.Force = true
+		case "--agent":
+			if i+1 < len(os.Args) {
+				i++
+				flagAgent = os.Args[i]
+			}
+		case "--agent-path":
+			if i+1 < len(os.Args) {
+				i++
+				flagPath = os.Args[i]
+			}
 		default:
-			// If not a flag, treat as PRD name (first non-flag arg)
 			if opts.Name == "" && !strings.HasPrefix(arg, "-") {
 				opts.Name = arg
 			}
 		}
 	}
+	cwd, _ := os.Getwd()
+	cfg, _ := config.Load(cwd)
+	opts.Provider = agent.Resolve(flagAgent, flagPath, cfg)
+	if err := agent.CheckInstalled(opts.Provider); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
 
 	if err := cmd.RunEdit(opts); err != nil {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
@@ -283,6 +338,15 @@ func runList() {
 }
 
 func runTUIWithOptions(opts *TUIOptions) {
+	// Resolve agent provider early (used for conversion, app, new, edit)
+	cwd, _ := os.Getwd()
+	cfg, _ := config.Load(cwd)
+	provider := agent.Resolve(opts.Agent, opts.AgentPath, cfg)
+	if err := agent.CheckInstalled(provider); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+
 	prdPath := opts.PRDPath
 
 	// If no PRD specified, try to find one
@@ -322,7 +386,8 @@ func runTUIWithOptions(opts *TUIOptions) {
 
 			// Create the PRD
 			newOpts := cmd.NewOptions{
-				Name: result.PRDName,
+				Name:     result.PRDName,
+				Provider: provider,
 			}
 			if err := cmd.RunNew(newOpts); err != nil {
 				fmt.Fprintf(os.Stderr, "Error: %v\n", err)
@@ -344,19 +409,19 @@ func runTUIWithOptions(opts *TUIOptions) {
 		fmt.Printf("Warning: failed to check conversion status: %v\n", err)
 	} else if needsConvert {
 		fmt.Println("prd.md is newer than prd.json, running conversion...")
-		convertOpts := prd.ConvertOptions{
-			PRDDir: prdDir,
-			Merge:  opts.Merge,
-			Force:  opts.Force,
-		}
-		if err := prd.Convert(convertOpts); err != nil {
+		if err := cmd.RunConvertWithOptions(cmd.ConvertOptions{
+			PRDDir:   prdDir,
+			Merge:    opts.Merge,
+			Force:    opts.Force,
+			Provider: provider,
+		}); err != nil {
 			fmt.Printf("Error converting PRD: %v\n", err)
 			os.Exit(1)
 		}
 		fmt.Println("Conversion complete.")
 	}
 
-	app, err := tui.NewAppWithOptions(prdPath, opts.MaxIterations)
+	app, err := tui.NewAppWithOptions(prdPath, opts.MaxIterations, provider)
 	if err != nil {
 		// Check if this is a missing PRD file error
 		if os.IsNotExist(err) || strings.Contains(err.Error(), "no such file") {
@@ -403,7 +468,8 @@ func runTUIWithOptions(opts *TUIOptions) {
 		case tui.PostExitInit:
 			// Run new command then restart TUI
 			newOpts := cmd.NewOptions{
-				Name: finalApp.PostExitPRD,
+				Name:     finalApp.PostExitPRD,
+				Provider: provider,
 			}
 			if err := cmd.RunNew(newOpts); err != nil {
 				fmt.Fprintf(os.Stderr, "Error: %v\n", err)
@@ -416,9 +482,10 @@ func runTUIWithOptions(opts *TUIOptions) {
 		case tui.PostExitEdit:
 			// Run edit command then restart TUI
 			editOpts := cmd.EditOptions{
-				Name:  finalApp.PostExitPRD,
-				Merge: opts.Merge,
-				Force: opts.Force,
+				Name:     finalApp.PostExitPRD,
+				Merge:    opts.Merge,
+				Force:    opts.Force,
+				Provider: provider,
 			}
 			if err := cmd.RunEdit(editOpts); err != nil {
 				fmt.Fprintf(os.Stderr, "Error: %v\n", err)
@@ -447,9 +514,11 @@ Commands:
   help                      Show this help message
 
 Global Options:
+  --agent <provider>        Agent CLI to use: claude (default) or codex
+  --agent-path <path>       Custom path to agent CLI binary
   --max-iterations N, -n N  Set maximum iterations (default: dynamic)
-  --no-retry                Disable auto-retry on Claude crashes
-  --verbose                 Show raw Claude output in log
+  --no-retry                Disable auto-retry on agent crashes
+  --verbose                 Show raw agent output in log
   --merge                   Auto-merge progress on conversion conflicts
   --force                   Auto-overwrite on conversion conflicts
   --help, -h                Show this help message
@@ -470,7 +539,8 @@ Examples:
   chief -n 20               Launch with 20 max iterations
   chief --max-iterations=5 auth
                             Launch auth PRD with 5 max iterations
-  chief --verbose           Launch with raw Claude output visible
+  chief --verbose           Launch with raw agent output visible
+  chief --agent codex       Use Codex CLI instead of Claude
   chief new                 Create PRD in .chief/prds/main/
   chief new auth            Create PRD in .chief/prds/auth/
   chief new auth "JWT authentication for REST API"

docs/guide/installation.md

@@ -8,7 +8,9 @@ Chief is distributed as a single binary with no runtime dependencies. Choose you
 
 ## Prerequisites
 
-Before installing Chief, ensure you have **Claude Code CLI** installed and authenticated:
+Chief needs an agent CLI: **Claude Code** (default) or **Codex**. Install at least one and authenticate.
+
+### Option A: Claude Code CLI (default)
 
 ::: code-group
 
@@ -27,8 +29,20 @@ npx @anthropic-ai/claude-code login
 
 :::
 
-::: tip Verify Claude Code Installation
-Run `claude --version` to confirm Claude Code is installed. Chief will not work without it.
+::: tip Verify Claude Code
+Run `claude --version` to confirm Claude Code is installed.
+:::
+
+### Option B: Codex CLI
+
+To use [OpenAI Codex CLI](https://developers.openai.com/codex/cli/reference) instead of Claude:
+
+1. Install Codex per the [official reference](https://developers.openai.com/codex/cli/reference).
+2. Ensure `codex` is on your PATH, or set `agent.cliPath` in `.chief/config.yaml` (see [Configuration](/reference/configuration#agent)).
+3. Run Chief with `chief --agent codex` or set `CHIEF_AGENT=codex`, or set `agent.provider: codex` in `.chief/config.yaml`.
+
+::: tip Verify Codex
+Run `codex --version` (or your custom path) to confirm Codex is available.
 :::
 
 ### Optional: GitHub CLI (`gh`)
@@ -238,11 +252,12 @@ chief --version
 # View help
 chief --help
 
-# Check that Claude Code is accessible
+# Check that your agent CLI is accessible (Claude default, or codex if configured)
 claude --version
+# or: codex --version
 ```
 
-Expected output:
+Expected output (example with Claude):
 
 ```
 $ chief --version

docs/reference/configuration.md

@@ -13,6 +13,9 @@ Chief stores project-level settings in `.chief/config.yaml`. This file is create
 ### Format
 
 ```yaml
+agent:
+  provider: claude   # or "codex"
+  cliPath: ""        # optional path to CLI binary
 worktree:
   setup: "npm install"
 onComplete:
@@ -24,6 +27,8 @@ onComplete:
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
+| `agent.provider` | string | `"claude"` | Agent CLI to use: `claude` or `codex` |
+| `agent.cliPath` | string | `""` | Optional path to the agent binary (e.g. `/usr/local/bin/codex`). If empty, Chief uses the provider name from PATH. |
 | `worktree.setup` | string | `""` | Shell command to run in new worktrees (e.g., `npm install`, `go mod download`) |
 | `onComplete.push` | bool | `false` | Automatically push the branch to remote when a PRD completes |
 | `onComplete.createPR` | bool | `false` | Automatically create a pull request when a PRD completes (requires `gh` CLI) |
@@ -83,17 +88,29 @@ These settings are saved to `.chief/config.yaml` and can be changed at any time
 
 | Flag | Description | Default |
 |------|-------------|---------|
+| `--agent <provider>` | Agent CLI to use: `claude` or `codex` | From config / env / `claude` |
+| `--agent-path <path>` | Custom path to the agent CLI binary | From config / env |
 | `--max-iterations <n>`, `-n` | Loop iteration limit | Dynamic |
-| `--no-retry` | Disable auto-retry on Claude crashes | `false` |
-| `--verbose` | Show raw Claude output in log | `false` |
+| `--no-retry` | Disable auto-retry on agent crashes | `false` |
+| `--verbose` | Show raw agent output in log | `false` |
 | `--merge` | Auto-merge progress on conversion conflicts | `false` |
 | `--force` | Auto-overwrite on conversion conflicts | `false` |
 
+Agent resolution order: `--agent` / `--agent-path` → `CHIEF_AGENT` / `CHIEF_AGENT_PATH` env vars → `agent.provider` / `agent.cliPath` in `.chief/config.yaml` → default `claude`.
+
 When `--max-iterations` is not specified, Chief calculates a dynamic limit based on the number of remaining stories plus a buffer. You can also adjust the limit at runtime with `+`/`-` in the TUI.
 
+## Agent
+
+Chief can use **Claude Code** (default) or **Codex CLI** as the agent. Choose via:
+
+- **Config:** `agent.provider: codex` and optionally `agent.cliPath: /path/to/codex` in `.chief/config.yaml`
+- **Environment:** `CHIEF_AGENT=codex`, `CHIEF_AGENT_PATH=/path/to/codex`
+- **CLI:** `chief --agent codex --agent-path /path/to/codex`
+
 ## Claude Code Configuration
 
-Chief invokes Claude Code under the hood. Claude Code has its own configuration:
+When using Claude, Chief invokes Claude Code under the hood. Claude Code has its own configuration:
 
 ```bash
 # Authentication