CodexLoop

Use codexloop when a task needs a durable execution harness rather than a single Codex turn.

The runtime implementation is co-located with this skill directory. After installation, the launcher ~/.codex/bin/codexloop imports the Python module from ~/.codex/skills/codexloop/.

Instructions

1. Confirm the global launcher exists at ~/.codex/bin/codexloop.
2. In the target repository, initialize the scaffold yourself. Do not ask the user to pre-create plan or memory files. init is responsible for generating them:

~/.codex/bin/codexloop init .

3. init generates these project-local files automatically:

• .codexloop/config.json
• .codexloop/doctor.sh
• docs/plans/implementation-plan.md
• docs/plans/CODEXLOOP_AGENT.md
• MEMORY.md

4. Fill in or refine the generated plan/doctor content as needed for the project, then generate or refresh the task backlog:

~/.codex/bin/codexloop plan --repo .

5. Execute the plan:

~/.codex/bin/codexloop run --repo .

6. Inspect or continue a run:

~/.codex/bin/codexloop status --repo .
~/.codex/bin/codexloop resume --repo .

What It Maintains

• docs/plans/active/*.md for the live plan and progress log
• docs/plans/completed/*.md for finished runs
• MEMORY.md for resolved failures and lessons
• .codexloop/ for runtime state, task worktrees, event logs, and config

Quick Reference

Task	Action
Initialize harness	~/.codex/bin/codexloop init .
Generate backlog	~/.codex/bin/codexloop plan --repo .
Execute plan	~/.codex/bin/codexloop run --repo .
Check progress	~/.codex/bin/codexloop status --repo .
Continue stopped run	~/.codex/bin/codexloop resume --repo .

Input Requirements

• A Git repository
• Codex CLI installed and authenticated
• ~/.codex/bin/codexloop installed via make install
• Permission to create project-local harness files with ~/.codex/bin/codexloop init .
• A concrete implementation plan in docs/plans/implementation-plan.md after initialization
• A repo-specific verification command in .codexloop/doctor.sh after initialization

Output

• Planned backlog in .codexloop/tasks/
• Live progress in docs/plans/active/
• Finished plan records in docs/plans/completed/
• Reusable failure memory in MEMORY.md
• Runtime state, worktrees, and Codex event logs in .codexloop/

Quality Gates

• The plan exists in docs/plans/implementation-plan.md
• The repo-specific doctor command is configured
• run completes with all tasks merged, or status explains what still needs intervention
• MEMORY.md is updated when failures are solved after retries

Examples

Example 1: Start a New CodexLoop Run

~/.codex/bin/codexloop init .
# edit docs/plans/implementation-plan.md and .codexloop/doctor.sh
~/.codex/bin/codexloop plan --repo .
~/.codex/bin/codexloop run --repo .

Example 2: Resume a Stopped Run

~/.codex/bin/codexloop status --repo .
~/.codex/bin/codexloop resume --repo .

Troubleshooting

Issue: codexloop is not found Solution: Run make install and either add ~/.codex/bin to PATH or call ~/.codex/bin/codexloop directly.

Issue: The run stops after retries Solution: Inspect docs/plans/active/*.md, MEMORY.md, and .codexloop/runs/*/tasks/* to see the last failing verification or Codex event log, then run ~/.codex/bin/codexloop resume --repo ..