Resume a long Codex task without starting over

1. Keep the objective attached to the work

A long conversation can contain several plans, abandoned approaches, and corrections. A useful handoff tells the next session which decision still applies. It does not need to preserve every message.

Continue the existing task when its objective is unchanged. If you start another session, give it the handoff and the exact project directory. A new conversation is not evidence that unfinished code has disappeared. In the CLI, the documented resume command can reopen a saved session; check that you are resuming the intended project.

codex resume

Reference: OpenAI: Codex CLI commands

2. Write a checkpoint the next session can use

Our handoff routine starts with the result we want and ends with one action the next session can take. Include file paths relative to the repository so another checkout can use the note. Update an existing project progress note if it already serves this purpose.

• Objective: what must work when the task is complete, plus the boundaries you agreed on.
• Current state: branch, changed files, and the part of the feature that already works.
• Evidence: the checks actually run, their results, and where to find the output.
• Failed attempts: approaches that were ruled out, with the reason. Keep the useful lesson, not the entire log.
• Next step: the smallest remaining action and the check that will tell you it succeeded.

3. Separate project instructions from task progress

AGENTS.md is a place for reusable project instructions: how to run tests, important conventions, and boundaries future tasks should respect. OpenAI documents how Codex discovers these files. A temporary list of unfinished tasks belongs in a progress or handoff note instead.

For example, keep the repository's test command in AGENTS.md. Keep 'the empty search state is done; keyboard focus still needs checking' in the task note. This makes the durable instructions easier to read and the current task easier to resume.

Reference: OpenAI: Custom instructions with AGENTS.md

4. Reconcile the note with the files

Ask the returning session to read the handoff, inspect the working tree, and explain any mismatch before editing. Another task may have changed a file after the note was written. If tests were run before the latest change, their result no longer covers that change.

Consider a search feature where filtering is implemented but the empty state is unfinished. The next task should inspect the existing filter, reproduce an empty search, then implement and verify the missing state. It should not rebuild the search feature from the original brief.

git status --short --branch
git diff --stat

Reference: Git: git diff

Try it in Codex

Prepare a useful handoff

Prepare a handoff for this task in the existing project progress note, or propose a suitable repository-relative file if none exists.

Include the objective, current branch, changed files, verified results, important decisions, failed approaches worth avoiding, remaining work, and the exact next step. Distinguish checks that passed from checks not run.

First inspect the current files and Git state. Preserve unrelated work. Do not change application code, commit, push, deploy, or start another task. Show me the note and any mismatch you found.

Check your result

• The note identifies the current objective and actual changed files.
• A later session can name its next action without reconstructing the entire conversation.
• Completed claims point to checks that cover the current code.
• Sensitive logs, credentials, and unrelated project details are left out.

Sources and scope

Official references support the product behavior described above. The task prompts and practical checks are our community guidance.

• OpenAI: Codex CLI commandsResuming saved CLI sessions; desktop controls are a separate interface.
• OpenAI: Custom instructions with AGENTS.mdProject instruction discovery and scope.
• Git: git diffInspecting current changes; the handoff structure is our practical recommendation.

Something changed in your version? Send a correction with the guide URL, platform, and version. Leave out credentials and private project content.