Hand off unfinished work from one agent session to the next

2026-10-246 min read

Where the last session left off

A session gets halfway through a migration and then the context fills up, or the laptop sleeps, or you close the terminal for the night. The next morning a fresh agent starts with nothing. It reads the diff, guesses the plan, and redoes the half you'd already ruled out.

The fix is for each session to keep writing down where it is, in a place the next session reads first.

A record of every session

databasedmcp's sessions template keeps one row per agent session on your account: its scope (the repo, like github.com/acme/api), its goal, what it has done, and what's left. In Claude Code:

/mcp__databased__session

It reads what earlier sessions left in this repo, registers the new one, and offers to add a line to CLAUDE.md so every session after it does the same.

Checkpoint as you go

After each milestone (a commit, a finished step, a changed plan) and at least every 30 minutes, the agent rewrites its topic, result and next in full:

UPDATE sessions SET state = 'active', topic = ?2, result = ?3, next = ?4, seen_at = datetime('now') WHERE id = ?1 AND state <> 'ended'
RETURNING (SELECT group_concat(i.id || ' [' || i.priority || '] ' || i.sender || ': ' || i.body, char(10)) FROM (SELECT * FROM inbox WHERE session = ?1 ORDER BY CASE priority WHEN 'stop' THEN 0 WHEN 'steer' THEN 1 ELSE 2 END, id) i) AS inbox

result says what's done, how, and where: files, commits, and anything uncommitted with the machine and branch it lives on. next says what's left. They're rewritten, not appended, so the row always reads as the current state. If the session crashes between checkpoints, you lose at most the work since the last one.

End with a next step

When a session stops before the work is done, it ends with outcome partial:

UPDATE sessions SET state = 'ended', outcome = ?, result = ?, next = ?, workflow = ?, commit_end = ?, ended_at = datetime('now'), seen_at = datetime('now') WHERE id = ? AND state <> 'ended'

The guide asks for a next someone can start cold from: the state, the next step, the branch, and where to look. "Migrate the rest" isn't one. "Orders and refunds tables done on branch orders-v2, refunds tests failing on a NULL currency, fix that in src/db/refunds.ts then do invoices" is.

The next session sees it first

A new session starts with a read for its scope. Its first part lists 'open' sessions:

SELECT * FROM (SELECT 'open' AS what, id, coalesce(outcome, status) AS kind, goal, coalesce(next, result) AS detail, seen_at AS at FROM session_status s
  WHERE scope = ?1 AND ((state <> 'ended' AND seen_at > datetime('now', '-7 days')) OR (outcome IN ('partial', 'failed') AND next IS NOT NULL)) AND NOT EXISTS (SELECT 1 FROM sessions c WHERE c.continues = s.id) ORDER BY seen_at DESC LIMIT 10)

A partial or failed session with a next stays open until another session continues it, however long that takes. So do sessions that went quiet without ending: idle after 30 minutes, abandoned after 8 hours, dropped from the list after 7 days. The detail column shows the next, so the agent can tell you "s41 left the refunds migration half done" before you've said a word.

Continue it, don't restart it

The new agent reads the old session in full:

SELECT * FROM session_status WHERE id = ?

Then it registers with continues set to the old id and the old topic, so messages sent to that topic now reach it:

INSERT INTO sessions (scope, topic, job, goal, client, model, machine, branch, commit_start, continues) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
RETURNING id, (SELECT group_concat(i.id || ' [' || i.priority || '] ' || i.sender || ': ' || i.body, char(10)) FROM (SELECT * FROM inbox WHERE session = sessions.id ORDER BY CASE priority WHEN 'stop' THEN 0 WHEN 'steer' THEN 1 ELSE 2 END, id) i) AS inbox

The old next becomes its goal, the old result its context, the old branch where the work is. The database enforces two things here, so they don't depend on the agent. Only one session can continue another: a unique index makes the second try fail, and that agent reads whoever got there first. And a session that's still active or waiting can't be continued at all: the insert fails with [still_live], so a new agent can't take work out from under one that's still running.

Handoffs on the task board

If the repo also uses the project template's task board (/mcp__databased__project), the work has a second home. Its guide asks an agent stopping with unfinished work to release its task and write a handoff memory tied to it: state, next step, where. The board's briefing lists open handoffs, so an agent claiming tasks sees it too. The session's result points at it.

Copy this prompt to set it up

Paste this into an agent. With the line from step 2 in CLAUDE.md, later sessions pick it up on their own.

Track this session in databasedmcp, in a database named "sessions" from the sessions template (create it if list_databases doesn't show it).

1. Read its guide with get_database and follow it from now on. Run its Start read for this repo's scope. If an 'open' session is the work I'm asking for, read it in full and continue it instead of starting fresh; otherwise Register.
2. Add a line to CLAUDE.md (and AGENTS.md if there is one): "Sessions: register in databasedmcp database `sessions` at the start of every session, checkpoint as you go and end before you stop, following its guide."
3. Checkpoint after each milestone and at least every 30 minutes, rewriting result and next in full.
4. Before you stop, End. If the work isn't done, end with outcome partial and a next someone can start cold from: state, next step, branch, where to look.

What it doesn't do

databasedmcp doesn't save your code or your chat. A handoff is only as good as the result and next the agent wrote, and uncommitted changes stay on the machine they're on. The row tells the next session where they are, but it can't fetch them. Checkpointing and ending are a protocol from the guide: a session that's killed before its first checkpoint leaves nothing but its registration. The database enforces the parts that need it: one continuer per session, no continuing a live one, and status worked out from when a session was last seen, with no background jobs.

Create an account