Recovering interrupted AI agent work

Recovering interrupted AI agent work starts with finding out what actually happened, before you run anything again. A crash, a usage limit hit mid-edit, a closed laptop or a killed terminal can each leave a different mess: a half-edited file, a migration applied once but recorded nowhere, a test server still holding a port or an agent process that is still running somewhere. The tempting move is to rerun the same prompt. That is the move most likely to make things worse, because a replay assumes nothing happened, and something almost always did. The workflow below has four steps: freeze, inspect, reconcile and resume deliberately. It works with Claude Code, Codex CLI or any agent working in a git repository. It is about getting the code and the records back into agreement. Writing a good note for the next session is a separate topic, covered in handing a session over.

Step 1: Freeze, and check what is still running

Do not relaunch yet. First establish whether the old run is really over. Look for agent processes and anything they started: test runners, dev servers, file watchers, package installs. A closed terminal does not always mean every child process ended.

When you check a process, do not trust the process ID alone. Operating systems reuse IDs, so the number you noted an hour ago may now belong to something unrelated. Match the ID together with the process start time and the executable path. If all three match, it is the same process. If any differ, it is a different process: do not kill it on the assumption that it is your agent.

If an unattended runner or a schedule might start the agent again, pause it now. Two agents working from the same half-finished state is the worst version of this problem. If you are unsure whether the old run is over, treat it as uncertain, not as finished and not as failed. The rest of the workflow is about resolving that uncertainty with evidence.

Step 2: Inspect what was written

Compare the working tree with the commit the run started from. git status shows modified and untracked files; git diff shows the content; git log shows any commits the agent made; git stash list catches stashes it may have created. Untracked files matter: generated fixtures, scratch scripts and partial outputs are common leftovers.

Then look for half-done edits. An agent stopped mid-write can leave a file that does not parse, a function renamed in one file but not its callers, or a test added without the code it tests. Run the build, the linter and the fast tests now, not to judge the task, but to find out what state the tree is in.

Check effects outside the repository as well. Did the run apply a database migration, write to a local service, publish a package or push a branch? These are the effects a replay is most likely to repeat. Finally, read whatever the run recorded: the task record, the run log and the agent's last output. Note where the record and the files disagree, because that gap is what Step 3 resolves.

Step 3: Reconcile the record with reality

You now have three accounts of the run: what the record says, what the files say and what the process state says. Reconciliation means deciding, for each piece of work, which account is true and updating the record to match.

There are three outcomes. Keep: the partial work is sound, the checks pass on it, and it becomes the starting point for the next session. Keep part: some files are good and some are not; restore the rest with git restore or by checking out the start commit's version. Discard: the state is unclear or wrong; return to the start commit and treat the run as never having happened, except for the lessons.

Any evidence recorded before the interruption may now be stale. A test result from before the last edits says nothing about the files as they are, so rerun the checks after you decide, and see stale test results for why that matters. Write the decision down: what you kept, what you discarded and why. A run that ended in an uncertain state should say so in its record, rather than being marked as succeeded or failed by default.

Step 4: Resume deliberately

Resuming is a new decision, not a continuation. Start a fresh session with an explicit authorization, a scope that reflects what is left and a short summary of the kept work: 'Steps 1 to 3 of ENG-14 are in the working tree and pass test_invoice_totals; step 4, the export change, is not started.' Do not paste the interrupted transcript and say 'continue'. It describes a state that no longer exists.

If your tooling records operations with IDs, retries become safer: an exact retry of a recorded operation should return the existing result rather than doing it twice, and a changed request reusing the same ID should be refused. Without that, assume nothing is idempotent and check before every repeated step, especially migrations and anything that appends.

Last, ask why the interruption happened. A usage limit suggests the task was too large for one session. A crash in the same test twice suggests an environment problem. Several interruptions in a row are a reason to stop and ask rather than to try again.

QUESTIONS

Is it safe to rerun the same prompt after an AI agent crashes?

Not until you have inspected the working tree. A replay assumes nothing happened, but an interrupted run usually left partial edits, untracked files or external effects such as an applied migration. Rerunning can duplicate those effects or build on a broken half-edit. Check git status and diff, run the build, decide what to keep, then start a fresh session.

What should I do when Claude Code or Codex hits a usage limit mid-task?

Treat the run as interrupted, not as failed or finished. Look at what changed since the starting commit, check whether files were left half-edited and run the fast checks. Keep or discard the partial work deliberately, then resume later in a new session with a summary of what is done. Consider splitting the task, since hitting a limit often means it was too large.

Why can't I trust a process ID to find a crashed agent?

Because operating systems reuse process IDs. The number you recorded may now belong to an unrelated program, and killing it could close something important. Match the ID together with the process start time and executable path. Only when all three match is it the same process; otherwise treat the old run's state as uncertain.

RELATED GUIDES

• How to read BRAIN FLUID reports and provenance
• How to preview work with the BRAIN FLUID harness CLI

RELATED HARNESS PAGES

• How to hand off an AI coding session How to hand off an AI coding session: a short end-of-session routine so the next agent or person can continue without guessing.
• Stale test results Stale test results describe code that has since changed. Bind each result to a revision and rerun checks on every completion attempt.
• When an autonomous agent run should stop and ask When an autonomous agent run should stop and ask: failed checks, missing approval, open blockers, impact obligations, out-of-scope writes or uncertain state.
• agent run history and reports Agent run history and reports: what to record about AI agent runs, how to read usage coverage honestly and where unknown differs from zero.