A Terminal Handoff That Survives a New Agent Session

A Terminal Handoff That Survives a New Agent Session

The rate limiter is half implemented. The middleware exists, two tests fail, and your coding agent has spent its last twenty minutes tracing a flaky clock dependency. Then the session ends. Tomorrow’s agent opens the same repository without knowing which failures matter or which edits were deliberate.

This is where I want a handoff, not a heroic reconstruction. There are two obvious approaches: paste the previous conversation into the next session, or leave a small, verifiable task checkpoint beside the code. Here is how they compare on the same unfinished change.

Transcript Dump and Repo Checkpoint, Side by Side

• The transcript approach preserves the conversation, including discarded theories, repeated tool output, and decisions that later changed.
• The checkpoint approach preserves the current objective, relevant files, verified results, unresolved questions, and one explicit next action.
• The transcript approach asks the next agent to infer which messages still describe the working tree accurately.
• The checkpoint approach asks the next agent to verify a short set of claims against the working tree.
• The transcript approach is quick when you already have a clean session summary available.
• The checkpoint approach takes a few minutes upfront but usually creates less ambiguity at restart.

The distinction is not long context against short context. It is historical evidence against an operational starting point. A transcript can explain why you rejected an approach; it should not be the only place recording what remains broken.

A Rate-Limiter Checkpoint the Next Agent Can Verify

I use a local HANDOFF.md file, kept outside the staged changes unless the team deliberately versions these notes. Before writing it, inspect git status --short and git diff --stat. Record the branch and HEAD commit, but remember that HEAD alone does not capture uncommitted edits.

• The objective is to return HTTP 429 after ten requests within one minute for each authenticated user.
• The current edits touch src/middleware/rate-limit.ts and tests/rate-limit.test.ts, with no intended dependency changes.
• The implementation injects a clock function because real timers made boundary tests unreliable.
• The last command was npm test -- rate-limit, which reported two failures in the minute-boundary cases.
• The next action is to inspect bucket reset behavior at exactly sixty seconds before editing assertions.
• The open question is whether anonymous requests should bypass this middleware or use an IP-based bucket.

Those are example checkpoint entries, not claims about your repository. Replace every path, command, and result with observed facts. Include the exact failing test names and a small error excerpt when useful. Never write “tests pass” when you only ran one filtered suite.

The First Five Minutes of the Replacement Session

For the transcript lane, the restart prompt is usually “continue where we left off,” followed by a large paste. The agent must recover intent before checking reality. That can work, but stale statements often look just as authoritative as recent ones.

For the checkpoint lane, I give a narrower instruction: “Read HANDOFF.md, inspect the diff, rerun the recorded test command, and report discrepancies before changing files.” This establishes a verification gate. If another developer changed the middleware overnight, the agent should discover that before applying yesterday’s plan.

Keep credentials, customer payloads, and unrelated logs out of both handoff formats. Review the diff yourself before any commit; a good checkpoint is not permission to stage everything.

Switching Agent Clients Without Losing the Task

Fluxo keeps the connection setup consistent: 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. Client configuration still varies; the handoff belongs in the repository, not in assumptions about a shared chat history.

You might resume work started with Claude Sonnet 5.5 using GPT-6.1 Sol. The checkpoint stays useful because it describes observable code state. Fluxo bills per real token, including cache reads and writes, with no monthly fee; do not assume a cache carries across models or clients. Users also earn a referral share when people they invite pay. If this fits your terminal workflow, consider creating a Fluxo account.

Verdict: Make the Checkpoint the Default Handoff

Use the repo-local checkpoint as the default, with selected transcript excerpts only when reasoning history matters. It is easier to audit, cheaper to reread, and explicit about uncertainty. The winning handoff lets the next agent prove where the task stands before taking another step.