Long-Running Agent Tasks skill for Codex

A long run is done well when the end state is verifiable by a command, every milestone leaves a green, committed checkpoint, the agent stops on its own when a gate keeps failing or a budget runs out, and the final report lets a reviewer trust the result without replaying the run.

Fit check before starting

Question	If no
Can “done” be checked by a command or measurable criterion?	Run /plan first and turn the outcome into checks
Does the work split into milestones that each leave the build green?	Restructure (expand-contract, feature flags) before going autonomous
Can it run inside the current sandbox without new access?	Grant the narrow access up front; do not plan on approving mid-run
Is the branch isolated from your daily checkout?	Use a worktree (see codex-parallel-worktrees)
Is there a usage budget and a wall-clock cap?	Set them now

Workflow

- [ ] 1. Write the goal: outcome, constraints, verification
- [ ] 2. Break into milestones with a gate each
- [ ] 3. Prepare the run: branch/worktree, permissions, notifications, notes file
- [ ] 4. Start the goal and let it run
- [ ] 5. Gate, commit, update notes at every milestone
- [ ] 6. Stop on a stop condition, or finish
- [ ] 7. Final verification and evidence report

1. Goal

Use /goal in the CLI, IDE extension or desktop app. The goal text becomes the first prompt and the completion criteria. It must contain:

Element	Example
Outcome	“All packages in packages/* compile as TypeScript in strict mode”
Constraints	“No explicit any; no public API changes; do not touch packages/legacy-billing”
Verification	“pnpm -r typecheck and pnpm -r test pass; pnpm size within 2% of main”

Goals are capped at 4,000 characters. For detail, write notes/plan/<slug>.md and set the goal to “Complete notes/plan/<slug>.md; follow its milestones and gates”. Manage it with /goal edit, /goal pause, /goal resume, /goal clear.

2. Milestones and gates

## Milestones
| # | Scope | Gate (must pass before commit) |
|---|---|---|
| 1 | Convert packages/utils | pnpm --filter utils typecheck && pnpm --filter utils test |
| 2 | Convert packages/api | pnpm --filter api typecheck && pnpm --filter api test |
| 3 | Enable strict at root | pnpm -r typecheck && pnpm -r test |
| 4 | Cleanup, docs | pnpm lint && pnpm -r test && pnpm size |

## Stop conditions
- Same gate fails after 2 distinct fix attempts -> stop, write findings, ask.
- Any change needed outside the declared scope -> stop and ask.
- Token budget 15M or 6 hours elapsed -> stop at the last green milestone.
- Anything destructive (data deletion, force push, deploy) -> never; ask.

3. Prepare the run

• Isolate: dedicated branch, ideally a worktree; clean git status.
• Permissions: sandbox and network the whole run needs, decided now. A goal never widens access; it pauses when it needs a decision. To avoid stalls on routine escalations without widening the sandbox, consider approvals_reviewer = "auto_review" (adds review model calls; denials still stop).
• Do not use -a never with danger-full-access outside a disposable VM or container.
• Notes: create the handoff file (see agent-handoff-notes) and tell the agent to update it at every milestone.
• Notifications: notify = ["python3", "/path/to/notify.py"] in ~/.codex/config.toml runs your program on agent-turn-complete with a JSON payload; the desktop app has system notifications and “Prevent sleep while running”.
• Machine: keep it awake and online; a laptop that sleeps ends the run.

4-5. Run, gate, checkpoint

Instruct the agent explicitly:

Work milestone by milestone from notes/plan/ts-strict.md. After each milestone:
run its gate; if green, commit with message "ts-strict: milestone N - <scope>"
and update notes/handoff/ts-strict.md (state, decisions, dead ends, next step).
Follow the stop conditions exactly. Do not skip or weaken a gate (no test
deletions, no `skip`, no `@ts-ignore` without listing it in the notes).

Check in occasionally without derailing it: a side chat (/side status?) or reading git log --oneline and the notes file. Steer with a follow-up message only when it is off course; queue (Tab in the CLI) anything that can wait for the next turn. Long commands run as background terminals: /ps shows them, /stop ends them.

Headless variant

For runs with no interactive client, drive milestones from a script:

codex exec --json --sandbox workspace-write "$(cat notes/plan/ts-strict.md) Do milestone 1 only." > m1.jsonl
ID=$(jq -r 'select(.type=="thread.started") | .thread_id' m1.jsonl)
pnpm --filter utils typecheck && pnpm --filter utils test || exit 1      # gate outside the agent
git add -A && git commit -m "ts-strict: milestone 1"
codex exec resume "$ID" --json "Gate passed and committed. Do milestone 2 only." > m2.jsonl

Running the gate outside the agent means a “done” claim cannot skip it. The SDK version of the same loop adds abort timeouts and usage checks per turn (see codex-sdk-automation).

6-7. Finish and report

Rerun every gate from a clean state at the end, then report:

## Long run report: ts-strict
**Outcome:** done | partial (stopped at milestone 3: gate failed twice) | aborted
**Branch:** feat/ts-strict (5 commits, one per milestone) — not pushed
**Final gates:** pnpm -r typecheck: pass | pnpm -r test: pass (1,284 passed) | size +0.4%
**Gate weakening:** none | <list of skips/ignores with reasons>
**Decisions:** ... **Dead ends:** ... (see notes/handoff/ts-strict.md)
**Usage:** 9.8M tokens, 3h40m
**Needs human:** review packages/api/src/serializers.ts typing approach

Gotchas

• Vague goals (“improve the codebase”) never terminate cleanly; the verification line is what lets the agent know it is finished.
• An agent under pressure to pass a gate may delete or skip tests, loosen types or widen lint ignores. Forbid it in the goal and diff-check for it in the report: git diff main --stat -- '*test*' and rg -n "ts-ignore|eslint-disable|\.skip\(" $(git diff --name-only main).
• Approval prompts stall an unattended run for hours; decide permissions up front.
• Compaction during a long run loses exact details; the notes file is the durable memory, and a SessionStart hook can reload it after compaction.
• Safety monitoring can pause a run; in the CLI a paused task ends. Restart from the last checkpoint and notes, not from scratch.
• Huge single commits at the end defeat review; one commit per milestone.
• Do not let the agent push, merge or deploy as part of the run; those are human steps.

Verification

• Every milestone commit passes its gate when checked out alone.
• Final gates pass from a fresh clone of the branch.
• No gate weakening appears in the diff, or each instance is listed and justified.