# Codex Loop

> Guides Codex Loop setup and long-running tracked execution by installing or refreshing the runtime, explaining activation headers, bootstrapping durable tracking artifacts, decomposing broad requests into tasks, and maintaining per-iteration memory and state. Use for Codex Loop installation, status, activation, or tracked restart-safe implementation, QA, review, and remediation loops. Do not use for one-off coding tasks that do not need Codex Loop or persistent tracking.

- Skill: `compozy/codex-loop` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add compozy/codex-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/compozy/codex-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: compozy (https://skillmd.com/u/compozy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/compozy/codex-loop

---


# Codex Loop

Use this skill for two lanes: runtime setup and restart-safe tracked execution.
The tracking lane creates project-local artifacts under `.codex/loop/<name>/`
so every continuation can resume from durable state instead of chat memory.

## Required Reading Router

Match the task to the row. Read the listed files in full before producing
output or running helper scripts. Inline content in this file is a dispatcher,
not the contract.

| Task | MUST read |
| --- | --- |
| Install, refresh, upgrade, status, uninstall, or explain activation | `references/runtime-setup.md` |
| Configure automatic continuations or project `codex-loop.toml` | `references/continuation-config.md` + `references/runtime-setup.md` |
| Bootstrap a tracked loop or create tasks from a broad request | `references/tracking-protocol.md` + `references/task-decomposition.md` + `references/state-schema.md` |
| Resume a tracked loop after a Codex Loop continuation | `references/tracking-protocol.md` + `references/phase-transitions.md` + `references/state-schema.md` |
| Audit or finalize a tracked loop | `references/checklist.md` + `references/phase-transitions.md` |

## Reference Index

- `references/runtime-setup.md`: install, upgrade, status, uninstall, activation header, and current runtime behavior.
- `references/continuation-config.md`: default built-in skill wiring with `optional_skill_name`, `optional_skill_path`, project config, and goal-header examples.
- `references/tracking-protocol.md`: bootstrap, one-action-per-iteration execution, memory-before-state sequencing, blockers, summaries, and done signature.
- `references/task-decomposition.md`: conversion of broad requests into task objects accepted by `init-tracking.py`.
- `references/state-schema.md`: authoritative `state.json` fields, status values, and invariants.
- `references/phase-transitions.md`: deterministic next-action mapping used by `detect-next.py`.
- `references/checklist.md`: required self-audit before iteration summaries and final completion.

## Helper Scripts

Resolve `<codex-loop-skill-dir>` to the directory containing this `SKILL.md`.
Invoke helpers with `python3 <codex-loop-skill-dir>/scripts/<name>.py`; do
not rely on the current working directory matching the skill directory.

| Script | Role | Purpose |
| --- | --- | --- |
| `scripts/init-tracking.py` | bootstrap, mutating | Create `.codex/loop/<name>/`, `request.md`, `state.json`, memory, and task files. |
| `scripts/detect-next.py` | read-only | Print the single next action for the current tracked loop. |
| `scripts/update-tracking.py` | mutating | Apply task, blocker, verification, and history transitions atomically. |
| `scripts/validate-tracking.py` | read-only | Validate tracking artifacts before summaries or final completion. |

## Procedures

**Step 1: Route the request**
1. Inspect whether the user needs setup/status help or active tracked execution.
2. For setup/status help, read `references/runtime-setup.md` and follow that lane only.
3. For continuation configuration, read `references/continuation-config.md` before advising or editing config.
4. For tracked execution, continue to Step 2.

**Step 2: Bootstrap or resume tracking**
1. Determine the loop name from the `[[CODEX_LOOP name="..."]]` header when present; otherwise derive a short kebab-case name from the task.
2. Run `python3 <codex-loop-skill-dir>/scripts/detect-next.py <name>` from the workspace root.
3. If the action is `bootstrap`, gather the original request and task list. If the user did not provide tasks, decompose the request first.
4. Run `python3 <codex-loop-skill-dir>/scripts/init-tracking.py <name> --request-file <path> --tasks-json '<json>'` or use `--request "<text>"` for short prompts.
5. **STOP. Read `references/tracking-protocol.md`, `references/task-decomposition.md`, and `references/state-schema.md` in full before bootstrapping or resuming tracked execution.** The bullets above are route markers, not the tracking contract.

**Step 3: Execute exactly one tracked action**
1. Re-run `detect-next.py` after bootstrap or at the start of every continuation.
2. Follow the printed action exactly: `execute_task`, `verify`, `resolve_blocker`, or `done`.
3. For `execute_task`, work on only the printed task. Write the iteration memory file before calling `update-tracking.py --complete-task`.
4. For `verify`, run the repository-appropriate validation command and only pass `--verify-pass` when real evidence supports it.
5. For `resolve_blocker`, clear blockers only after the underlying issue is actually resolved and recorded in memory.
6. **STOP. Read `references/phase-transitions.md` in full before updating state.** The helper output is authoritative for the next action.

**Step 4: Audit, summarize, and stop**
1. Run `python3 <codex-loop-skill-dir>/scripts/validate-tracking.py <name>` before printing an iteration summary.
2. Fill `assets/iteration-summary.template.md` and make it the final block of the assistant message for non-final iterations.
3. For `done`, run `validate-tracking.py <name> --expect-done`, print the summary, then print the literal contents of `assets/done-signature.txt` on the final line.
4. **STOP. Read `references/checklist.md` in full before claiming an iteration or loop is complete.** The checklist is the completion gate.

## Error Handling

- If `init-tracking.py` reports that state already exists, switch to resume mode and run `detect-next.py`.
- If a helper reports invalid JSON or an invalid transition, fix the input or complete the missing prerequisite; do not hand-edit `state.json`.
- If validation fails, record the failure as a blocker with `update-tracking.py --blocker "<summary>"`, print an iteration summary with `outcome=blocked`, and stop.
- If the repository verification fails, fix production code or task artifacts rather than weakening checks; then rerun verification before marking `PASS`.