Supervise codex-plan-loop as the chat-session controller. Let fresh worker
codex exec phases do the progress and review work, while the active Codex
session launches the wrapper, monitors it, explains it, and stops for decisions.
Start A Run
-
Confirm the target repository and plan file.
- Work from the target git repository root.
- If no plan file is provided or multiple candidates are plausible, ask for the exact file.
-
Run preflight checks before asking to start:
git rev-parse --show-toplevel
git status --porcelain=v1
command -v codex-plan-loop
command -v codex-plan-log
test -f <plan-file>
-
Require explicit confirmation before starting.
- Report the repository, plan file, clean-worktree result, and exact command.
- State that
codex-plan-loopauto-commits each accepted progress/review slice. - Use existing CLI defaults unless the user specified options: max 20 cycles,
workspace-write, no network, review limit 5, live logs. - Do not start when the worktree is dirty unless the user explicitly instructs a different cleanup or isolation plan.
-
Start the command in a long-running terminal session so the conversation can continue:
codex-plan-loop <plan-file>
Use user-provided options exactly, for example:
codex-plan-loop <plan-file> --max-cycles 1 --network --model <model>
Monitor A Live Run
- Poll the running session and report phase-level updates: progress phase start/finish, review phase start/finish, commits, stop statuses, Bucket II decisions, and validation failures.
- Keep chat updates compact. Do not mirror verbose transcripts unless the user asks.
- If the user asks for status, report the current phase, latest visible event, latest saved run directory if known, and whether the process is still running.
- If the user asks to stop, interrupt the running process, then inspect saved state with
codex-plan-log show latest --json. Explain that partial runs can lackfinal-summary.json. - Do not leave a required command session running silently at the end of a response.
Inspect Saved Runs
Prefer the deterministic helper before opening raw files:
codex-plan-log show latest --json
codex-plan-log list
codex-plan-log path <run-id|latest>
codex-plan-log transcript latest
codex-plan-log transcript latest cycle-1-progress
codex-plan-log events latest
codex-plan-log events latest cycle-1-review-1 --json
Explain from the summary outward:
- run id, run directory, and final status
- stop reason or completion summary
- phase timeline: progress phases, review passes, validation, and commits
- Bucket II decisions and whether they block remaining plan work
- raw paths for follow-up inspection
Use raw artifacts only when the helper output is not enough:
final-summary.json: wrapper final state and aggregated Bucket II itemscycle-*-progress-parsed.json: structured output from$progress-runcycle-*-review-*-parsed.json: structured output from$post-review-loop*.transcript.log: readable phase transcript*.stderr.log: Codex progress stream and wrapper messages*.jsonl: rawcodex exec --jsonevent stream
Stop And Decision Handling
When the wrapper exits with blocked, decision_needed, failed, or
validation_failed:
- Inspect
codex-plan-log show latest --json. - Read the relevant transcript or events for the stopped phase.
- Explain the evidence and distinguish wrapper-level status from worker phase status.
- Ask focused questions for the needed decision or external change.
- Do not auto-rerun, auto-recover, or implement Bucket II items unless the user explicitly asks.
Interpretation Notes
codex-plan-looprequires a clean worktree before starting and writes private run logs under.git/codex-plan-loop/.- The wrapper uses fresh
codex execturns; the active chat session is the supervisor, not the worker. - A phase can succeed while the wrapper later stops because review found blocking Bucket II, validation failed, or the review limit was reached.
- Missing
.git/codex-plan-loop/means no wrapper runs were saved in that repository. - Missing
final-summary.jsonusually means the wrapper exited before its final reporting path or was interrupted.