codex-goal-loop

Make Codex /goal runs stop drifting.

Codex /goal can run for a long time, but the objective is short and easy to overinterpret. This repo gives Codex a better operating pattern: write the real goal into GOAL.md, put durable loop rules in AGENTS.md, and launch /goal with a short command that points at those files.

Install

Inside Codex:

/skills install --repo rendrag-git/codex-goal-loop --path .

Restart Codex after installation.

Then ask:

Use the goal-loop skill to help me write GOAL.md and the /goal command for this repo.

Quick Start

The skill helps you write GOAL.md first, then gives you a short /goal command.

Recommended command shape:

/goal Pursue the current goal in GOAL.md under the Goal-Loop Conventions in AGENTS.md. Re-read GOAL.md before each iteration, keep its state concise, verify before checking acceptance items, and call update_goal complete only when every acceptance item is proven with evidence.

That command should stay short. The full spec belongs in GOAL.md, not in the slash command.

Why This Exists

Codex /goal turns a thread into a self-continuing loop. After every idle turn, Codex injects a continuation prompt and keeps going until the goal is complete, budget-limited, paused, cleared, interrupted, or plan mode suppresses continuation.

The loop has two common failure modes:

1. The objective text is wrapped as task data. It can still steer the model, but durable rules belong in AGENTS.md.
2. The loop follows the last piece of evidence. Without a state file, it can keep polishing a local artifact while the real product target stalls.

This pattern fixes both.

The Pattern

Add three things to the repo you want Codex to work in:

1. Goal-loop rules in AGENTS.md Codex re-reads project instructions. Durable loop rules go there.

2. A structured GOAL.md This is the source of truth for the outcome, non-goals, acceptance criteria, blockers, and evidence.

3. A short /goal command The command points at GOAL.md and AGENTS.md. It does not restate the full spec.

The installed skill can do this for you.

What The Skill Does

• Reads repo docs before asking questions.
• Helps write or repair GOAL.md.
• Produces a short /goal command that does not conflict with the docs.
• Adds goal-loop conventions to AGENTS.md.
• Keeps GOAL.md as a state tracker, not an action log.
• Checks that completed acceptance items have evidence.
• Supports optional SQLite state for users who do not use Linear.
• Explains token budgets and stopped-loop behavior.

Example

Instead of this:

/goal Build the app, keep working until it is fully done, make sure tests pass, update docs, track everything, do not forget deployment, do not drift...

Use this:

/goal Pursue the current goal in GOAL.md under the Goal-Loop Conventions in AGENTS.md. Re-read GOAL.md before each iteration, keep its state concise, verify before checking acceptance items, and call update_goal complete only when every acceptance item is proven with evidence.

Then put the real detail in GOAL.md:

## Required Capabilities

1. **CAP-1: Working user path**

   Acceptance:
   - [ ] CAP-1.1 User can complete the happy path.
   - [ ] CAP-1.2 Failure cases show clear errors.
   - [ ] CAP-1.3 Verification command passes and is recorded in Progress.

More examples:

• Minimal Markdown goal loop
• SQLite-backed local state

Optional SQLite State

Users without Linear can mirror goal state into a local SQLite DB:

python3 scripts/goal_loop.py init-db --db .goal-loop/state.sqlite
python3 scripts/goal_loop.py import-md --goal GOAL.md --db .goal-loop/state.sqlite
python3 scripts/goal_loop.py audit --goal GOAL.md --db .goal-loop/state.sqlite

Keep .goal-loop/ gitignored in the target repo. SQLite is a local machine-readable mirror. GOAL.md remains canonical if they disagree.

Setting A Token Budget

The /goal slash command does not expose token_budget. Use a normal chat instruction:

Use the create_goal tool. objective: "Pursue the current goal in GOAL.md under the Goal-Loop Conventions in AGENTS.md. Re-read GOAL.md before each iteration, keep its state concise, verify before checking acceptance items, and call update_goal complete only when every acceptance item is proven with evidence." token_budget: 2000000.

create_goal fails if the thread already has an active goal. Use a fresh thread, or clear, pause, or reset the existing goal first.

Repair A Drifting Goal

Run:

python3 scripts/goal_loop.py audit --goal GOAL.md

The audit catches common problems:

• checked items without evidence
• missing Bridge notes
• verbose Progress entries
• SQLite and GOAL.md status mismatches

Then ask Codex:

Use the goal-loop skill to repair this GOAL.md before continuing the /goal run.

Templates

• templates/AGENTS-goal-loop.md
• templates/GOAL.md
• templates/goal-state.schema.sql

Share

Copy-paste launch posts are in docs/share-posts.md.

License

MIT.