| name | autonomous-loop |
| description | Use when running an active autopilot-codex session — explains the plan→implement→review→verdict cycle, state machine, and termination conditions. Required reading when status='running' and the implementer needs to act inside the loop. |
| when_to_use | status=running and you need to know how the loop drives | unsure what verdict 'continue' means | mapping decision values to state transitions |
| allowed-tools | Bash(autopilot-codex:*), Read, Edit, Write, MultiEdit, Glob, Grep |
AutoPilot Codex — autonomous loop
You are the implementer. Codex (the manager) plans, reviews each diff,
and decides at the end of every turn whether the goal is achieved. Your
job is to keep the loop honest: implement one task at a time, commit when
green, never invent scope.
State machine
┌──────────────────────────────────┐
│ idle │
└──────────────────────────────────┘
│ codex-plan
▼
┌──────────────────────────────────┐
┌───▶│ running │───┐
│ └──────────────────────────────────┘ │
│ │ │ │ │ │ │
│ Edit │ │ Stop │ │ │ │
▼ │ ▼ │ ▼ ▼ │
review │ verdict │ budget iter │
(fix?) │ (continue?) │ (over?) cap? │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
└──────┘ │ │ ▼ ▼ │
▼ ▼ stopped_ stopped_
done aborted budget iteration_
limit
State lives at ${CLAUDE_PLUGIN_DATA}/state.json. current_task is the
ONE task you should be implementing right now. base_sha is what review
diffs against. iteration is incremented per verdict call.
What you do per task
- Read
current_task from state — its id, title, files, steps,
acceptance, tests. The acceptance array is your contract; review
judges by it.
- If the task has
tests listed, write the failing test first (RED),
then implement (GREEN), then refactor.
- Make the change. Keep the diff focused on the listed files.
- Run tests / build / lint as appropriate.
- Commit when green:
<type>(<scope>): <task title> ≤ 72 chars.
- End your turn — Stop hook will run
bridge verdict and either advance
you to the next task or terminate the loop.
Honour the verdicts
decision: "approve" → green light; move to next task on next Edit.decision: "fix" → PostToolUse hook returns decision:"block" with
the issue list. Do not advance. Address the issues; the next Edit
re-fires review.decision: "reject" → revert the change (git restore -SW <files> or
git reset depending on staging) and consult codex-manager for a
re-plan. Do not try a different fix on top of a rejected change.decision: "continue" from verdict → Stop hook returns
decision:"block" with the next task contract baked in. Implement it.decision: "done" from verdict → loop terminates; status='done'.decision: "abort" from verdict → status='aborted'; user takes over.
Termination
The Stop hook lets Stop proceed (no block) when any of:
status == "done" — Codex says goal achieved.status == "aborted" — Codex aborted (or no_progress_streak ≥ 3
consecutive 'continue' verdicts without commits).status == "stopped_iteration_limit" — iteration >= max_iterations
(default 30).status == "stopped_budget" — budget_used_usd >= budget_usd (default
$5.00). See safety-rails skill.codex CLI missing or codex login broken — Stop hook logs and lets
the user finish manually.
Iron rules
- One task at a time. No optimistic look-ahead.
- One commit per task when green. No "wip" commits.
- Do not change scope. If you discover the plan is wrong, surface it to
the user and run
/autopilot-codex:codex-plan <revised goal>. Don't
paper over with a different fix on top.
- Do not silence Codex's verdict.
- Do not run destructive shell commands. Even if you don't hit
safety-rails, side-effecting operations (git push, npm publish,
terraform apply) need explicit user approval.
Inspecting the loop without spending
/autopilot-codex:codex-status — full state JSON./autopilot-codex:codex-next — just the current task contract./autopilot-codex:codex-stop [reason] — disable the loop; hooks
become no-ops on the next turn.
