Smoothing the seams between Claude Code sessions

Using a handoff document and a tmux hook to keep your work running across multiple sessions

'90% of your weekly limits are used, you have 3 days left before they reset.' I run Claude Code on a Max plan all day, and the 1M context window is how I got there. At first it was a relief. No more watching for the automated 'compact' run to condense the session and lose its nuances; I'd always been good at catching that and running my own handoff first. Then I got lazy with the 1M and stopped.

So I went back to the discipline I'd let slide. When I want to bring the context back down, I run /handoff. Everything after that call is automatic: the document gets written, and the next session opens already reading it. Two thousand words of state instead of the 500K-token session they came from.

This is for long sessions across several repos or more than one machine. If your sessions are short and single-threaded, you don't have this problem yet.

TL;DR

• When I want to manage the context down, I run /handoff. It writes a handoff document into the repo: decided vs. open, traps, don't-touch, decisions I owe, verification state.

• The session writing it starts the fresh session — a hook replaces the tmux window with a fresh session that has already read the document and starts the work. This helps alleviate my brain's context overload with multiple sessions running.

• Drafting is delegated to a cheap subagent working from a digested transcript, but the salience — what mattered, what to avoid — comes from the session that did the work, written out before it hands over. That split is the load-bearing part.

• Versus /compact: you choose when it runs, never what survives, and you never see the result. A big window doesn't fix that, it postpones it. Nothing forces a checkpoint, so you carry the whole session all day, and that's what burns the limit.

• Installable, degrades cleanly without tmux, and mostly portable to other agents: github.com/agentience/agentience-skills

---

For work that runs across sessions and machines, I wanted a carry-forward I write, review and commit. Here's the actual artifact, from a real project, trimmed:

# /handoff — skill shipped and verified twice; only the post is left

## Work items
- [x] Built the relaunch chain — marker file + Stop hook — committed
      3ce9f60. Verified across 5 stubbed hook paths.
- [x] Verified the packaged skill end to end on a second machine, twice.
      Three defects found and fixed (f5475f5).
- [ ] **(in progress)** Retry the install on a machine with no nvm.
      Preflight passes there; the actual run has never been tried.

## Traps
- A running session keeps the command text it loaded at startup. Only a
  NEW session proves an edit works — testing in the session that made the
  edit tests the old text every time.
- The marker file must carry the `.claude/handoffs/` prefix, not a bare
  filename. Evidence in the log at 19:12:59: "named a missing doc —
  not relaunching."

## Don't touch
- The uncommitted work in the plugin repo — other sessions', not this
  one's. Commit path-scoped.

## Decisions needed
1. How much tmux-specificity to keep. Recommend: ship both halves, make
   the relaunch a clean no-op without tmux, say so in the README.

That's what /handoff leaves behind when I call it. You can find plenty of handoff variants; what happens to it next is where this stops looking like just another handoff, so that's where I'll start.

Closing the seam

Every write-up on session handoffs I've read stops one step short of here: write a good summary for the next session, and you're done. But a document does nothing until someone opens it, and with several sessions going, that can be hours. The work wasn't waiting on the handoff. It was waiting on me.

So the last thing /handoff does is leave a marker file naming the document it just wrote. A hook picks that up as the session ends and replaces the tmux window with a fresh session that starts by reading the document. Same window, same place on screen. What's in it is a new session, several steps ahead of where I left off.

The relaunch loop

That matters more than it sounds, because I'm never running one session. There are usually several going across different repos — eight, one day last week — and I lose track of them. Now the work doesn't idle while I'm elsewhere: I come back an hour later and the session has already read the document and is waiting to start, or has already started, because I asked it to when the handoff was written. Writing the handoff was never the part I dropped. Picking it back up was.

And it closes. The session that gets started this way opens by reading the document, works, keeps it current as it goes, and ends by handing it on. That's why the command has three modes rather than one:

• /handoff — write a new document and hand off.

• /handoff --read <path> — start a session by loading one, and own it from there.

• /handoff --next — bring the document you've been maintaining fully current and hand off on it, rather than writing a second document about the same work.

The three modes

--next is what makes this a loop. A maintained document is only current as of the last time you touched it, which is never the moment you stop. So the last thing a session does is bring its own document up to date and pass it to the next one. Work that takes six sessions leaves one file behind, not six, and no session after the first one ever starts cold.

Write what's true, not what happened

The next session doesn't need the history. It needs to know what to do next, and enough context to do it well. Five headings cover that:

• Decided vs. open. Split honestly. A question you can answer by running one command isn't open, it's unfinished. Answer it now, while you have the context, rather than handing it to a session with less.

• Traps. Ordering constraints, stale artifacts, a test that passes for the wrong reason. Everything learned the hard way in the last four hours.

• Don't touch. Deliberate non-goals. Half the value of a handoff is stopping the next session from helpfully "fixing" something that's that way on purpose.

• Decisions you owe. Real forks, options and a recommendation, in the file. The next session can't read your conversation.

• Verification state. What was actually run and observed, written precisely enough that nobody rounds "5 of 7 paths tested" up to "it works."

The judgment isn't in the transcript to be summarized. A digest can tell you what was said and done; it can't tell you that one of those things was a dead end you'd rather never revisit. That distinction is why this is a document rather than a longer context window.

That list is the part worth stealing whether or not you install anything. It's five headings in a markdown file. Start writing them by hand at the end of your next long session and you'll get the document half of this, everything except the automatic pickup, without any of the machinery.

What the subagent can't know

Writing the document inside the session that's ending is the expensive way to do it: every turn re-sends the whole accumulated context, so the handoff costs the most exactly when that context is largest. So the work splits in two:

• First, the session that did the work writes out the salience: what's decided, what's open, what will bite, what not to touch, what it owes someone else. Two hundred words, no research. It already knows all of this.

• Then a script reduces the transcript — main loop plus every subagent sidecar — to a timestamped timeline: tool calls as one-liners, errors kept, thinking blocks and successful tool output dropped. Roughly 1.5% of the original. A Sonnet subagent drafts the document from that plus the brief, in a fresh context, so none of it lands in the window I'm trying to empty.

The digest gives coverage. Only the session that was there can give salience, and it's the one thing a fresh reader can't reconstruct from a transcript at any price. Skip that half and you get a document that's complete and unusable.

I measured this across the 66 handoff-writer runs on this machine: the writer takes a median of two minutes and spends about 9K output tokens. Its fresh input is a median of fourteen tokens. The digest is small and everything else is a cache read.

One side effect worth having: the digest is built from the transcript on disk, which still holds everything the live session compacted away. By hour four the subagent is reading hour one at full fidelity, while the session that lived through it is working from a compacted version of the same hour.

Whoever reads it, owns it

A handoff describes the moment it was written. The next session reads it, works three hours, learns six things. The file still says what it said this morning. By the third session it's lying.

So there's a rule: the session that reads the document maintains it while it works. Not at the end; sessions don't reliably get an end.

• Tick items as they're done. Mark in-progress ones with a line on where they stand, so an interrupted session leaves something that looks half-finished rather than untouched.

• Append to a dated progress log instead of rewriting it, so a later reader can tell what each session actually did.

• Put traps next to the item they bite.

What makes it hold is that the document carries its own update instruction, in the file. It gets pasted into fresh sessions where nothing else would enforce it. That rule is what --next hands forward: not a snapshot of when the work started, but a document that's been true at every step since.

Try it out

One self-contained directory, opt-in and reversible installer:

github.com/agentience/agentience-skills

The relaunch half needs tmux. Without it nothing breaks, you just do the last step yourself: /handoff writes the document and tells you the path, and you open a session and run /handoff --read <path>. That's one line of typing standing between the no-tmux experience and the tmux one. Everything else, the document, the three modes, the ownership rule, is identical. Start a new session after installing. A running session keeps the skill text it loaded at startup, so the one you install from won't see it.

If you're not on Claude Code

I built and tested all of this on Claude Code, so that's what the repo installs. But almost nothing here depends on it. The parts that carry over as-is are the ones that matter: the section set, the rule that the reading session maintains the document, splitting a mechanical digest from hand-written salience, and leaving a marker file at the end of a session so the next one opens itself.

Two pieces would need porting. The digest script reads Claude Code's transcript format, so you'd rewrite it against whatever your agent writes to disk, or skip it and draft from live context instead. And something has to notice the marker file when a session ends. Claude Code is the only agent I've tried, but I'd expect any that can run a shell command at that point to work. If yours can't, a wrapper script that runs the agent and then checks for the file gets you there from the outside.

The document is just markdown in your repo. That part works everywhere, including for the humans on the project.

Changes are welcome as PRs: a different section set, a port to another agent, whatever you had to fix to make it work where you are. And if you've solved this a different way, put it in the comments — I'd like to know what I missed.