Hand Off an Unfinished Agent Task Without Losing State
Hand Off an Unfinished Agent Task Without Losing State
The worst agent handoff is “keep going where we left off.” The next session cannot reliably reconstruct your intent from a dirty working tree. It needs three things: the actual changes, evidence of what works, and a small restart plan. Here is the terminal workflow I use when a task outlives its context window.
This walkthrough assumes an existing Git repository, a POSIX-compatible shell, and a Node project whose test suite runs with npm test. The example task is adding pagination to search results. Substitute your actual task details, but keep the handoff structure.
1. Put the unfinished pagination work on a branch
Run these commands from the repository root, one command per paragraph. Check your current branch before creating a dedicated handoff branch:
git status --short --branch — git switch -c handoff/search-pagination
Switching branches does not checkpoint anything. It simply gives the unfinished work a named home. If that branch already exists, switch to it without the -c flag instead of creating it again.
Inspect tracked changes and list untracked files separately. An ordinary diff does not include new files:
git diff HEAD --stat
git diff HEAD — git ls-files --others --exclude-standard
Before proceeding, identify unrelated edits, generated output, and anything containing credentials. The handoff commit should contain task work, not everything your terminal happens to see.
2. Capture the current test result before explaining it
Run the test suite and save its output outside the repository. Capture the exit status immediately, before another command replaces it:
npm test > /tmp/search-pagination-tests.log 2>&1; test_status=$?; tail -n 60 /tmp/search-pagination-tests.log; printf '\nTest exit status: %s\n' "$test_status"
A failing checkpoint is acceptable. An undocumented failing checkpoint is expensive. Record the exact failing test names and distinguish observed failures from guesses about their cause. If the suite never starts because dependencies are missing, write that instead of claiming the implementation fails.
3. Write a restart note beside the code
Create a short, tracked handoff file with explicit fields:
printf '%s\n' '# Search pagination handoff' '' 'Goal: Add pagination to search results.' 'Completed: REPLACE with implemented behavior and file paths.' 'Remaining: REPLACE with unfinished behavior.' 'Validation: npm test' 'Observed result: REPLACE with exit status and failing test names.' 'Decisions: REPLACE with constraints and rejected approaches worth preserving.' 'Next action: REPLACE with one concrete edit or investigation.' > .agent-handoff.md
Open the note in your editor and replace every placeholder before committing. Be specific: “Add a test for an empty final page” beats “finish tests.” Include relevant paths, but do not dump the entire conversation.
- Describe completed behavior without implying that untested code already works.
- Record existing failures separately from failures introduced during this task.
- State which files or interfaces the next agent must preserve.
- Give the next session one small, immediately executable first action.
4. Commit only the work the next agent needs
Stage tracked changes interactively, then stage the note: — git add -p
git add .agent-handoff.md — Interactive staging does not include untracked files. For each new task file listed earlier, run git add followed by its explicit path. Avoid blanket staging when unrelated work or secrets might be present.
git diff --cached --check — git diff --cached
git commit -m "WIP: checkpoint search pagination for agent handoff"
git status --short — Review anything left unstaged. A commit does not preserve those leftovers for another checkout. Include necessary task files before ending the session, or explicitly document why unrelated changes remain.
5. Restart from the checkpoint, not the old conversation
In the next session, verify the checkout before allowing edits: — git branch --show-current
git log -1 --oneline — git status --short
cat .agent-handoff.md — Give the agent this instruction: “Read .agent-handoff.md and inspect the checkpoint commit. Reproduce the recorded validation result before editing. Start with the documented next action, preserve the stated constraints, and update the note when stopping.”
I keep this workflow independent of the model. With Fluxo, one key and the base URL https://api.fluxorelay.com support Claude Code, Codex, Gemini CLI, and any OpenAI SDK. A handoff from Claude Sonnet 5.5 to GPT-6.1 Sol still rests on Git and reproducible evidence, not shared conversational memory.
Fluxo bills per real token, including cache reads and writes, with no monthly fee. Invited users’ payments also earn the inviter a referral share. If you want to try this across your agent tools, consider creating a Fluxo account.