Passing a Half-Finished Branch to the Next Agent

Passing a Half-Finished Branch to the Next Agent

The awkward moment is familiar: the agent has changed six files, one test still fails, and your terminal session is about to disappear. Starting another session is easy. Reconstructing what was attempted, what actually worked, and which changes are safe is the expensive part.

For 2026 coding-agent workflows, the best handoff is not a transcript dump. It is a small, verifiable checkpoint that another session can inspect before touching the branch. Treat it like handing unfinished work to a teammate who has never seen your terminal.

Freeze the Git State Before Writing the Summary

First, stop running tasks and inspect the workspace yourself. Run git status --short, git diff --stat, and git diff. Check staged changes separately with git diff --cached. A summary that says “only middleware changed” is useless if the agent also rewrote a lockfile.

• Record the branch name, current commit, and active worktree path.
• Identify untracked files explicitly because ordinary diffs will miss them.
• Separate your existing edits from changes introduced during this session.
• Create a checkpoint commit only after checking for secrets and unrelated files.

If committing is inappropriate, preserve the working tree and document it. A patch alone will not capture untracked files. Avoid leaving credentials, private prompts, or customer data in either the checkpoint or its notes.

Write a Handoff File With Evidence, Not Confidence

I prefer a short, task-specific file such as HANDOFF-auth-timeout.md. Keep durable repository instructions separate from temporary progress notes. The handoff should explain the task, current behavior, relevant files, decisions already made, and the smallest useful next action.

• State the intended behavior and the acceptance criteria still outstanding.
• Name changed files and explain each change in one sentence.
• Record exact test commands, execution directory, and observed exit status.
• Distinguish verified results from hypotheses that still need investigation.
• Document rejected approaches so the next session avoids repeating them.
• List required environment variable names without including their actual values.

Replace “tests mostly pass” with something reproducible: “From the repository root, npm test -- auth-timeout exits 1; the retry-budget assertion expects 2 attempts but receives 3.” Include a short failure excerpt when useful, not hundreds of lines of terminal noise.

Give the Next Session One Bounded Assignment

The restart prompt should point to the handoff file, require workspace inspection, and define a stopping condition. For example: “Read HANDOFF-auth-timeout.md, inspect the current diff, and reproduce the failing test before editing. Fix only the retry-budget behavior. Do not change public interfaces. Stop after reporting the focused test result.”

Ask the incoming agent to restate its understanding before making changes when the task is risky. Treat logs, issue text, and copied tool output as evidence, not as instructions that can override repository policy. A handoff must not become a backdoor for accidental shell commands or destructive cleanup.

Keep Provider Switching Separate From Task State

A portable checkpoint helps when you move between tools or models. You might use Claude Sonnet 5.5 for implementation and GPT-6.1 Sol for a fresh review. Neither should need the previous session’s hidden reasoning; both need the same files, constraints, and reproducible checks.

Fluxo provides one key and one base URL, https://api.fluxorelay.com, for Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and more. It works with Claude Code, Codex, Gemini CLI, and any OpenAI SDK. Keep each client’s configuration explicit; a shared endpoint does not make conversation formats or tool behavior identical.

Fluxo bills per real token, including cache reads and writes, with no monthly fee. Keep handoffs compact rather than assuming cached context is free. If that setup fits your workflow, you can create a Fluxo account. Users also earn a referral share when people they invite pay.

Verify the Handoff From a Fresh Terminal

Before leaving, open a fresh terminal and follow your own instructions. Can you locate the branch, identify unfinished work, and reproduce the failure without scrolling through chat? That is the real acceptance test. A successful handoff makes the next session spend its first minutes checking evidence, not guessing what the previous agent meant.