loopback

Loopback iterative development loop

Quick start (recommended)

1. Start directly (by default it enters "wizard mode")

/loopback "修复 X。完成后输出 <promise>DONE</promise>。" --completion-promise "DONE" --max-iterations 10

Notes:

• If the current environment supports interactive input,/loopback it enters the wizard by default: first it shows the global steps, then helps you refine parameters and contracts step by step
• If the current environment does not support interactive input,/loopback it outputs an overview of the steps, and fails directly when key contracts are missing (to avoid running astray)
• To skip the wizard: add --no-wizard

1. Not sure how to pass parameters: first look at the parameter description (it will not create a state file or start the loop)

/loopback --guide

1. Parameters look okay: first use --dry-run for a dry run (it will not create a state file or start the loop)

/loopback "修复 X。完成后输出 <promise>DONE</promise>。" --completion-promise "DONE" --max-iterations 10 --dry-run

1. Formal start

/loopback "修复 X。完成后输出 <promise>DONE</promise>。" --completion-promise "DONE" --max-iterations 10

What is Loopback?

Loopback is an iterative development methodology based on the Ralph Loop idea, adapted to the Codex CLI environment.

Core concept:

while true; do
  # 从 .codex/loopback.local.md 读取同一条 PROMPT
  # 运行 Codex 一轮（例如：codex exec）
  # 检查停止条件（max-iterations / completion-promise / cancel）
  if is_complete; then break; fi
done

The same prompt is repeatedly sent to Codex. Codex "sees" its previous work through the following:

• Modified files in the file system
• git history
• previously generated code

⚠️ Note: Codex CLI itself will not "automatically repeat the same prompt". Loopback uses a state file .codex/loopback.local.md to persist context, and then a driver script repeatedly calls codex exec to implement the loop.

Each iteration:

1. Codex receives thesameprompt
2. works on the task, modifies files
3. tries to complete
4. checks the completion conditions
5. if incomplete, proceeds to the next iteration
6. sees previous work and gradually improves
7. until completion or until the maximum number of iterations is reached

Command

/loopback [OPTIONS]

Start a Loopback loop in the current Codex session.

Usage:

/loopback "重构缓存层" --max-iterations 20
/loopback "添加测试" --completion-promise "TESTS COMPLETE"
/loopback "修复认证 bug" --dry-run

Options:

• --max-iterations <n> - maximum number of iterations (default: unlimited)
• --completion-promise <text> - completion promise phrase (stop when this phrase appears)
• --guide - output a lightweight parameter description (does not start the loop)
• --wizard - force enable the wizard flow (already enabled by default; some environments automatically downgrade to non-interactive preflight)
• --no-wizard - skip the default wizard (run directly with the original parameters)
• --allow-infinite - allow a missing stop contract (dangerous: may run indefinitely; not recommended)
• --dry-run - only show the plan, do not execute
• --no-run - only create the state file, do not start the driver (for manually running the wrapper/debugging)
• --reuse-session - reuse the same Codex session (default, more like Ralph Loop's "same conversation" iteration)
• --fresh-session - start a new Codex session each round (more isolated, but less of a "self-referential conversation")

/cancel-loop

Cancel the active Loopback loop.

Usage:

/cancel-loop

Note: do not pass the cancel command as a prompt to /loopback(for example /loopback /cancel-loop). Cancellation should use /cancel-loop, or manually delete .codex/loopback.local.md。

Completion promise

To mark a task as complete, Codex must output a <promise> tag:

<promise>TASK COMPLETE</promise>

Loopback looks for this specific tag. Without it (or --max-iterations), Loopback will run indefinitely.

Recommended "contract style" (makes the loop easier to converge)

It is strongly recommended to write the "completion criteria" in the PROMPT like a verifiable contract, rather than just saying "say DONE when finished". For example:

目标：修复认证 bug。
验收：
- `pytest -q` 全绿
- 复现步骤 A 不再报错
完成后输出：<promise>DONE</promise>
若未完成：说明阻塞点 + 下一步要做什么 + 哪些验证已完成/未完成（不要输出 promise）

Best practice: require a "stop contract" by default

To avoid running indefinitely (especially in non-interactive environments), Loopback by default requires you to provide at least one stop condition (satisfying any one is sufficient):

• --completion-promise 'DONE'
• --max-iterations 10

If you really want to allow an infinite loop (not recommended), you need to explicitly declare it:

• --allow-infinite

Implementation details: the driver writes each round's output to .codex/loopback.outputs/iteration-N.log, and detects in that output whether <promise>COMPLETION_PROMISE</promise>。

A more robust implementation: in --reuse-session mode, the driver uses codex exec --json/codex exec resume --json, from the JSON event thread.started.thread_id to get session_id, avoiding reliance on local session filename/date inference.

Also: when "the current directory is not a git repo", the driver automatically adds codex exec to --skip-git-repo-check, so you can directly run test cases in something like ~/Documents/GitHub , a "repository collection directory" (it is still recommended to run in the target repository root to improve speed/reduce context noise).

Self-reference mechanism

"Loop" does not mean Codex talks to itself. It means:

• The same prompt is repeated
• Codex's work is persisted in files
• Each iteration sees previous attempts
• Gradually builds toward the goal

Example

Interactive bug fixing

/loopback "修复 auth.ts 中的令牌刷新逻辑。当所有测试通过时输出 <promise>FIXED</promise>。" --completion-promise "FIXED" --max-iterations 10

You will see Loopback:

• Attempt a fix
• Run tests
• See failures
• Iterate on the solution
• In the current session

When to use Loopback

Suitable for:

• Goals with clear definitions and clear success criteria
• Tasks that require iteration and improvement
• Iterative development with self-correction
• Brand-new projects

Not suitable for:

• Tasks that require human judgment or design decisions
• One-off operations
• Goals with unclear success criteria
• Debugging production issues (use targeted debugging instead)

Differences from Ralph Loop

Feature	Ralph Loop (Claude Code)	Loopback (Codex)
Environment	Claude Code CLI	Codex CLI
Iteration mechanism	stop hook	File state check
State storage	.claude/ralph-loop.local.md	.codex/loopback.local.md
Command	/ralph-loop, /cancel-ralph	/loopback, /cancel-loop
How it works	Intercept exit signal	Check completion condition

How it works

Initialization

When running the /loopback command:

1. Create the .codex/loopback.local.md state file
2. Set the initial iteration count to 1
3. Record the maximum number of iterations and the completion promise
4. Save the original prompt

Iteration process

Each iteration, the driver will:

1. Read .codex/loopback.local.md
2. Run codex exec(the same PROMPT)
3. Write output to .codex/loopback.outputs/iteration-N.log
4. Check stop conditions:
   • Whether --max-iterations
   • Whether <promise>COMPLETION_PROMISE</promise>
   • Whether the status file was deleted by /cancel-loop (treated as cancellation)
5. If the stop condition is not met: increment iteration and proceed to the next round

Cleanup

When running /cancel-loop :

1. Check whether .codex/loopback.local.md exists
2. If it exists, read the current iteration count
3. Delete the status file
4. Report the cancellation status and iteration count