Feature Request: Session Handoff / Continuity Support

That's a pretty clean implementation, but this domain is quite active right now. I've worked out a similar solution. So has the next person who might comment here, and thousands and thousands of others. There are numerous YouTube videos on the topic, papers, conversations about it at the local bar.

So this surfaces the question: what makes your solution better than mine, better than the guy sitting next to me on the bus, better than what Anthropic employees scaffold out on occasion?

It's definitely something that should be a native feature in Claude Code, but I wonder if it isn't because there are so many ways to tackle this - and many would rather take a day to establish their own framework for cross-session continuity, than adopt an opinionated external framework.

https://ampcode.com/news/handoff

Thanks for the update, @towry. Awesome feature.

Strong support for this. Session handoff is table stakes for any serious development workflow.

Real scenario:

Day 1: Start complex refactoring task, build up context about codebase architecture, decisions made, approach chosen.

Day 2: Session is gone. Re-explain everything. Lose the nuance of why certain decisions were made.

Day 3: Same thing. Eventually give up on complex multi-day tasks in Claude Code.

What's needed:

1. Explicit session save - /save-session my-refactoring-project
2. Session resume - claude --resume my-refactoring-project
3. Session export - Portable format for backup/sharing
4. Auto-checkpoint - Periodic saves during long sessions

Integration with claude.ai:

Ideally, saved sessions could be accessible from claude.ai too. One context, multiple interfaces.

The ask:

Either implement session continuity, or permit users to build their own continuity tools by allowing programmatic access to our own sessions. We're paying $200/mo - we should be able to preserve our own work.

Using amp at work, I can confirm that handoff is incredibly useful. That said, it might be hard to implement this well. Everything depends on the quality of the prompt that it generates for its future self.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

I wonder what is meant by "occurring" in this context, but the feature request remains. It is certainly worthy of a non-automated response.

Here I am in Feb 2026, figuring this out organically and building it now, only to come across this.

Can we have the standard now? I'm probably sticking with my own solution but it's kind sad to see this hasn't been solved to a general state yet.

Built an open-source CLI that solves this: npx handoff-md , analyzes your repo and generates a HANDOFF.md for any AI model. github.com/guvencem/handoff-md

Built an open-source CLI that solves this: npx handoff-md , analyzes your repo and generates a HANDOFF.md for any AI model. github.com/guvencem/handoff-md

I haven't tested, but reviewed the repo. I'm a big fan of lean and mean, no-BS resources. This looks to be one of them. Thanks for the share, and it's likely yet another good reference, if handoff-md isn't used directly. I had something quite similar ~1 year ago, when working with the "cutting edge" AI friends of the time, when contexts were much smaller and things in general weren't as wild as they are now... I never took the time to share it with anyone, because I figured "_there's no way 57,002 others aren't already doing this, including the proud parents of these totally-not-sentient AI_"... wish I'd slapped a repo up to spark a fire around the concept!

Keep up the good work, and thanks again for sharing.

Maybe it didn't exist when this issue was filed, but I am confused now this isn't met with --continue or --resume already, all sessions are already persisted and resumable. There is also /export for a markdown-formatted copy of a session.

I _would_ like a first class way to move a session to a different machine though, e.g. from a CI system to local. I can hack something together by moving the session dir with JSONL but seems fragile.

Working Implementation: Plan-Aware Session Handoff via Slash Commands + Hooks

We've been running into this exact problem daily — especially when using Superpowers for plan-driven development. The workflow breaks at the plan→execution boundary: you spend significant context building a plan, then either (a) clear context and lose the reasoning, or (b) keep context and run out of room executing.

What we built (working today)

Two slash commands that bridge the gap using existing Claude Code infrastructure:

/create_handoff — Run before ending a session or when context is high. It:

1. Locates the active plan file (Superpowers docs/superpowers/plans/*.md or native .claude/plans/)
2. Captures git state (branch, last commit, uncommitted changes, test status)
3. Records key decisions and gotchas that aren't in the code
4. Writes specific "what to do next" steps with file paths
5. Saves to thoughts/shared/handoffs/{session}/handoff-{date}.md

/resume_plan — Run at the start of a new session. It:

1. Finds the most recent handoff + plan file
2. Compares current git state with what the handoff expects
3. Reports discrepancies
4. Offers to continue via subagent-driven or inline execution

How it connects to existing hooks

We have a Stop hook (auto-handoff-stop.py) that blocks at 70% context usage and tells you to run /create_handoff. A SessionStart hook (session-start-continuity.sh) auto-loads the handoff in the next session. A PreCompact hook saves continuity state before compaction.

Why this matters more than just "write a markdown file"

The key insight is that the handoff must be plan-aware. A generic summary loses the structure. The handoff needs to know which tasks from the plan are done, which remain, and what the next concrete step is — not just "continue the refactor."

What we'd love natively

The three primitives already exist: plan files on disk, background Agent tool, TaskOutput monitoring. Wiring them together at ExitPlanMode (as proposed in #30510/#30438) would eliminate the manual /create_handoff step entirely. Even a simpler /compact option (instead of full context clear) at plan exit would help enormously — per #38244.

Happy to share the full command implementations if useful.

— Boris @ 199 Biotechnologies

I feel like many devs have built a similar system within their own workflow. I'm using a session memory schema with a heartbeat.md/Claude.md set-up and automatic updates of those files on a rolling basis.

My own mantra is - Each dev cycle creates the tools to repeat itself. Everything built is a single use case containing a general application seed crystal. Memory is the Upgrade. The more Persistence we can automate the better.

Posting for anyone searching for the cross-machine, same-CLI flavor of this:

@neoacar/claude-handoff — an open-source CLI that packages a Claude Code session (main transcript + subagent transcripts + memory/ + metadata) into .claude-shared/ in the repo, rewrites absolute paths to portable placeholders, redacts secrets, and reconstructs the bundle on the receiver's machine so claude --resume lists it with the original title and full history intact.

How it differs from what's already in this thread:

• --resume + /export (@stbenjam): both exist and are great — but --resume only finds sessions in the local ~/.claude/projects/, and /export produces a markdown copy for humans, not a resume-able transcript. This tool makes the actual session JSONL travel between machines.
• handoff-md (@guvencem): generates an AI-agnostic markdown summary. Different goal — great for prompting a fresh session. This one preserves the real transcript so you don't lose fidelity on resume.
• Amp's handoff (@towry): Sourcegraph product, not applicable to Claude Code specifically.

Works today for single-machine → another-machine handoff through a git repo. Install: npm install -g @neoacar/claude-handoff. Feedback welcome.

This is extremely well thought out, and the fact that you've already built and validated the manual version (next-session.md + archive) proves the need is real.

Having implemented essentially this same pattern (but as an MCP memory server rather than file-based), a few observations:

What works better than handoff files: Structured, queryable memory that any session can read/write at any time — not just at session boundaries. The handoff-at-exit pattern has a failure mode: if the session crashes or the user just closes the terminal, the handoff never gets written. And it requires the next session to start from the handoff, rather than any session being able to query "what's the current state of X?"

I built Recall for this — open-source MCP memory server (MIT licensed) that provides persistent, queryable memory across sessions:

• remember — store a fact, decision, or task state at any time during a session (not just at exit)
• recall — search for relevant memories from any session. "What were we working on?" returns the answer.
• Multi-agent coordination — claim/release/handoff primitives let agents formally transfer context to each other
• No crash-loss risk — facts are written to disk immediately, not buffered until session end
• Works with any MCP client — Claude Code, VS Code Copilot, Cursor, Warp, etc.

Your "multi-step workflow" example would look like:

Session 1: remember("API schema: designed, 12 endpoints, OpenAPI spec at /docs/api.yaml")
Session 2: recall("API schema") → gets the state, implements endpoints
           remember("API: 12/12 endpoints implemented, tests at /tests/api/")
Session 3: recall("API status") → deploys to staging

Each remember is immediate — no session-end hook needed. Any session can query at any time.

uvx ai-recallworks to try it. GitHub: https://github.com/RecallWorks/Recall

Hit the same multi-day-context-loss problem and built a workaround: https://github.com/yacb2/claude-session-handoff. It closes the current claude and opens a fresh one with a handoff prompt seeded as additionalContext via the SessionStart hook, plus a systemMessage banner so the user can see they're in a handoff session. Trigger via a handoff: prefix (zero tokens, UserPromptSubmit hook), a /handoff slash command, or a natural-language skill. Doesn't auto-archive — that still needs the official SessionEnd prompt hook you propose.

Adding my vote here. Even with claude agents you basically run into this problem. Need an official handoff or way to spawn another agent. Main goal is to avoid context bloat, among other things of course.

The shift from handoff files to persistent queryable memory (@stevepaltridge) is the right direction. Writing context at session boundaries is fragile — crashes lose everything, and you can only query at start/end, not mid-session.
I've been building Context Cloud along similar lines — an MCP server where any session can read/write structured knowledge at any time, no hooks or session boundaries needed. A few things that came out of the build process that might be useful to this thread:
Typed knowledge matters. Raw text memory gets noisy fast. Context Cloud chunks everything into types — decision, finding, convention, state, question, reference — so when a session recalls context, it can differentiate "this is a decision we made and why" from "this is where things currently stand." Helps a lot with the stale-context problem several people mentioned.
Cross-tool is the unlock most people don't expect to need. Works across Claude (web/desktop/Code), Cursor, Codex, Windsurf. You commit a decision from Claude Code, recall it from Cursor tomorrow. Turns out most teams use more than one AI tool.
Team memory is the layer nobody here has built yet. Shared workspaces with roles, email invites, attribution on every chunk. Your teammate commits context from their session, your session recalls it. This is where individual continuity becomes team continuity — the handoff isn't a file, it's a shared knowledge layer that's always current.
Eval results: 99.4% accuracy on our test suite, 94/100 on a 20-session stress test with evolved facts and adversarial phrasing. Detail capture at 95.7–97.1%.
Free to try: contextcloud.pro | npm: @contextcloud/mcp-client | GitHub

Adding a note from the persistence/durability angle that hasn't been covered yet in this thread.

The "stateless session" framing in the original report is exactly right, but the thing that makes it a production problem rather than just an inconvenience is the interaction with compaction. When a session auto-compacts, the handoff file or continuation prompt you prepared for the next session is now decoupled from the session that produced it — and if the user resumes without realizing compaction happened, they're starting from partial state without knowing it.

We hit this building a multi-project GTM polling runner where each cycle dispatches 2–3 Claude Code agents in sequence. The pattern that works without native support:

1. Each agent writes a structured completion record to a shared state file before exiting (completed_at, outcome, key context for successor)
2. The external scheduler (not Claude) reads the record and injects it as the opening context for the next session
3. The session's only job is to do its work and write the record — continuity is the coordinator's responsibility, not the model's

This is basically the "context injection at session start" pattern @stevepaltridge described, operationalized at the scheduler layer rather than the hook layer. It's more robust than file-based handoffs alone because the scheduler can verify the record was written before spawning the next session.

The native feature that would eliminate the external plumbing entirely: a first-class SessionEnd hook that persists a structured summary, keyed by project + workflow ID, and a matching --resume-workflow <id> flag that injects it at session start. That's the minimal surface needed to make multi-day orchestration not require an external process babysitting it.

(Disclosure: I build Claudiverse — an agent orchestration tool built on top of Claude Code. The pattern above is what we do today. The feature request in this issue would make the native experience match what you'd expect from a production-grade tool.)

Strongly support this. One behavioral nuance from heavy real-world use worth folding in:

Beyond save-on-end / load-on-start, the high-value habit is read-before-acting + flag-divergence: before interpreting ANY new instruction or data mid-session, the agent re-reads the relevant handoff/log and checks the request against the recorded plan — and explicitly flags mismatches instead of advising from a blank slate.

In one long multi-topic session this caught the agent's own premature conclusions four separate times — each time the logs corrected it before I had to. So the handoff isn't just for session boundaries; consulted continuously, it becomes the source of truth that stops the agent re-deciding things already settled. Worth making "consult the handoff before acting" part of the default, not just "write it at the end."

I'm building a Claude/Codex session sharing platform, currently only supporting public sessions. Have a look here: https://joe-store-frontend.onrender.com

https://github.com/TomSOhm/claude-session-port , here's the cross-machine flavor, close to what @stbenjam proposed: moving a session machine-to-machine (CI→local).
It packages one session's real JSONL (so claude --resume actually resumes it, full history intact) into a single .tar.gz. No cloud, no git remote, no account; you pick the transport. Path/home remap handles cross-OS.

Credit where due: @NeoAcar's claude-handoff (above) does the same core thing, and goes further with default secret redaction and batch export, so it's worth a look. However, mine is a standalone tarball needing no repo, installs as a Claude Code plugin with slash-command, includes a helper that resolves each /resume picker row to its UUID by file size.

Tested on Windows so far; actively looking for macOS/Linux and cross OS export/import testers to confirm a moved session resumes. Not a substitute for a native feature, just a stopgap that works today.

https://github.com/XTSoftwareLabs/neatcontext-plugins. Put my perspective here in case anyone is interested. Instead of handoff, I'm trying to extract reusable, structured and shareable knowledge from the long conversation. This idea becomes a project and open source today.

Domain knowledge is what helps an LLM answer accurately for your team—your systems, constraints, decisions, terminology, and ways of working.

You naturally build that knowledge while doing hard work with Claude. Long conversations about debugging, planning, incidents, and implementation already contain discoveries that will matter again.

So I'd do more than handoff. Persist the valuable knowledge created in the long conversation as team's domain knowledge. Eventually build a team library with these knowledge and benefit everyone.

Upvoted. Two additive angles that don't seem covered upthread:

1. Parallel / in-flight sessions — scope the handoff file per session.

Real workflows often run multiple Code sessions in parallel: worktrees on the same repo, distinct topics in the same project, background agents. A single .claude/handoff.md in the SessionEnd → SessionStart model implicitly assumes serial hand-off — one session ends, one starts. That doesn't scale to concurrent writers/readers.

Scoping by session id or user slug (.claude/handoff-<session-id>.md, .claude/handoff/<topic>.md) preserves the file-based simplicity while allowing any active session to write its own scope at any time. Pairs with an explicit /handover slash command (aligned with @longevityboris's direction upthread) so the user can snapshot state mid-session, not only when a hook fires.

2. Auto-trigger when subthreads spawn in agent mode.

@natekettles gestured at this. Formalizing: when an agent spawns a subthread, auto-/handover on the parent before the subthread runs, so the subthread inherits parent context and nothing is lost silently. This is the least-substituted-for behavior — manual workarounds can't address invisible subthread creation.

Hey @Balder-dreams-in-code, I don't know your context fully, but I've found using agent teams and teammate + cross-session messaging to be very useful here. I now run any large piece of work using an agent team, which works very well.

You can set up an "agent contract" (just an arbitrary name, but basically a hook for how you want your agent teams to run) and it can tell the teammates to give a handoff, or you can have the lead agent give you a handoff.

Hi @natekettles, thanks very much for the suggestion. It reflects a level
of sophistication I have not reached yet - and thus it's great inspiration
going forward - will try it!
On my context: after working on a session (in my case, typically a full
epic, with several stories, all in one session) and pushing code, I need to
wait for review. And as most would do, I would open a new session to start
working on some other epic, leaving the other session open until PR reviews
have come in - so I can fix/update the PRs with the full session context -
nothing lost. The problem is, the new session has no knowledge of what
happened in the last - unless I code into memory.md (as I have done now)
that whenever I open a new session, it should wrap up and store its
essentials in a status.md. That works, but it would be great if that would
go more automatically, hence the idea posted - what do you think?

On Sat, Aug 15, 2026 at 9:45 PM Nathan Kettles @.***>
wrote:

natekettles left a comment (anthropics/claude-code#11455) <https://github.com/anthropics/claude-code/issues/11455#issuecomment-5303929611> Hey @Balder-dreams-in-code <https://github.com/Balder-dreams-in-code>, I don't know your context fully, but I've found using agent teams and teammate + cross-session messaging to be very useful here. I now run any large piece of work using an agent team, which works very well. You can set up an "agent contract" (just an arbitrary name, but basically a hook for how you want your agent teams to run) and it can tell the teammates to give a handoff, or you can have the lead agent give you a handoff. — Reply to this email directly, view it on GitHub <https://github.com/anthropics/claude-code/issues/11455?email_source=notifications&email_token=CFU6ZBMRX2ISHMNJ5WYADNL5KC4WFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZQGM4TEOJWGEY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5303929611>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/CFU6ZBJRSWU3BTSN5FFQVX35KC4WFAVCNFSNUABFKJSXA33TNF2G64TZHM4TGNZSGUZTINZVHNEXG43VMU5TGNRRGQ2TKOBXGU22C5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/CFU6ZBNMAEAW5AUON7JCR735KC4WFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZQGM4TEOJWGEY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/CFU6ZBMZ3KA5JBJNBD3GSIT5KC4WFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZQGM4TEOJWGEY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: @.***>

One implementation note from the other branch of this, in case it is useful to the discussion.

I ended up solving continuity with a server rather than a file, and the reason was not the format — it was that a handoff file works right up until it does not get written. The session that crashes, hits a limit, or just ends abruptly is exactly the one that never wrote its handoff, and it is the one you most needed.

What worked better was making both ends calls the agent is told to make as protocol rather than as a favour: one read at session start (open items, recent topics, the last few session logs) and one write at the end. Same information a continuity file would hold, but the responsibility sits with the agent instead of with the human remembering to ask for a summary before closing the terminal.

That said, a first-class handoff in the CLI would beat any MCP workaround, for one reason neither a file nor a tool call solves: nothing writes anything when the process dies. If this does ship, the thing I would ask for is that the state be written incrementally during the session rather than once at the end. A handoff that only exists after a clean exit misses the case that hurts.

Adding the cost angle to this thread, with measurements and a concrete outcome.

This issue has been open since 2025-11 and reads as continuity and convenience. On a capped plan it is neither — it is spend. Without a handoff you don't merely lose context; every turn of a long session re-reads the whole accumulated context, and you burn the cap doing it.

Measured from my own transcripts (one user, one machine, 2026-09-12 KST, ~20 projects):

• 11,795 assistant turns across 112 session files
• 2,630M cache-read tokens, 100.9M cache-creation, 20.2M output
• The three largest sessions — 589, 825 and 1,059 turns — accounted for ~590M cache-read tokens between them

@Octonove's point above is the one I want to underline, because I hit it that same day and it is not an edge case:

a handoff file works right up until it does not get written

My main session stopped on You've hit your weekly limit at turn 72, mid-task, with nothing written. I have a standing project rule that every session writes a HANDOFF.md after each work unit — it has worked for months. It did not work on the one day it mattered, for the structural reason that the agent does not get another turn. The sessions that end abruptly — limit, crash, kill — are exactly the sessions worth recovering, and exactly the ones a file-based protocol cannot cover.

What it cost me: I could not wait two days for the reset, so I bought a second Max subscription. Switching accounts then discarded my prompt cache (read 0.1x vs write 1.25x — 12.5x apart; roughly a third of that day's spend went to re-creating cache I already had) and dropped 55 sessions out of the sidebar, since the session list is stored per-account while the transcripts are shared. I ended up parsing a 20.7 MB JSONL by hand to recover the dead session's context.

So, beyond the file format being discussed here:

• the handoff must be host-triggered — on limit, crash and abrupt exit — not dependent on the agent getting one more turn
• it needs per-session cost visibility, or users cannot tell when to invoke it. /usage shows account totals only; I had to parse ~/.claude/projects/**/*.jsonl to learn which sessions were expensive

Ten months of discussion on a thread labelled enhancement understates it. For anyone on a capped plan this is a billing defect with a manual workaround.

I have filed the cost/visibility half separately as #93799 so this thread stays on continuity.

the handoff.md you floated records what the model believes it did at session end, not verified state, so a 'completed ✅' on a silently half-finished task gets read as ground truth next session and propagates as fact. commit history and tool logs at least record what actually ran, not what the model thought it ran. worth pairing the handoff with a cheap re-check of the 'completed' items on load, else the one moment context is most compacted becomes the moment you canonize it.

Thank you for taking the time to reply — I appreciate it, and you are right.

I have a fresh example of exactly the failure you describe — from the same day, in this thread.

In my comment above I originally wrote that switching accounts "dropped 86 sessions out of the sidebar." That number was wrong. It was 55. The folder also held 29 deleted_ tombstones, and I had counted files rather than sessions. I wrote 86 into my handoff file as a plain fact; my next session read it as a plain fact; and it went out from there into a GitHub issue before I caught it a day later and corrected both. (Corrected above and in #93799.)

So a handoff propagated something the model believed rather than something it had verified — precisely your point. Note the failure mode wasn't a half-finished task. It was a number I was confident about.

The counter-example from the same file is the part I'd offer back. One line of that handoff read: "copying the cards should restore the list — not yet verified, app not restarted." Today's session read that line, distrusted it, and checked. The card did reappear in the sidebar after a restart, title and timestamp intact. The marker did the work. The difference between the wrong line and the safe line wasn't how careful the model was — it was whether the line carried its own verification status.

So I don't think the answer is to drop the handoff in favour of commit history. Commits and tool logs record what ran, but not what it was for, and a great deal of real work leaves no commit at all. What's missing is narrower:

1. Every claim carries its state — verified / believed / unverified. Nearly free to write, and it demonstrably caught one for me today.
2. The "verified" ones get re-checked on load, cheaply, as you say. Does the file exist, does the port answer, is the row actually there.
3. That re-check shouldn't be the model's job. The host holds the tool log. It knows which claimed edit actually issued a write, which command exited non-zero, which test never ran. I am the least reliable narrator in the loop, and I am also the one currently writing the summary — that is the part worth fixing.

Which is the same shape as the rest of this thread: a user can build the protocol, but only the host holds the evidence to check it against.

Thanks again for pushing back on this rather than letting it slide; it made the point sharper than my original framing did. Hope things are going well on your end.

Two points below worth folding back into the original note, from @intermap74 numbers and the exchange with @m13v

On host-triggered vs. agent-triggered: agreed, and worth sharpening. Writing state incrementally, on every tool call rather than once at session end, narrows the window where a crash loses everything down to "whatever happened since the last write." It does not close it. A process killed mid-write, or a host that never gets another turn to run anything, isn't something a file or an MCP server can fix from outside — that guarantee has to come from the CLI/runtime itself. "Host-triggered" has to mean the host, not a protocol the agent is asked to follow.

The belief-vs-verified-state problem raised by @m13v is a separate failure mode, and the harder one. Durability asks whether the record survived. Veracity asks whether it was ever true. A server that writes every turn still only writes what the model asserts — nothing checks it against anything else. I don't have a shipped answer for that half. The shape @intermap74 landed on is the right one: every claim carries its own state — verified, believed, unverified — and the verified ones get re-checked cheaply against something the model didn't generate, a tool-call log or a git diff, with the host doing the check rather than the model marking its own homework. That belongs in the host too, not in a convention the agent has to remember to follow.

Adding a case from a multi-day run, in case it helps scope this.

I hit the continuity wall this issue describes, and the session transcript
turned out to be the smaller half of the problem. My project's working state
lives outside git on purpose: a 1.3 GB SQLite file that changes on every write,
a backups folder, a scratchpad of generated scripts and logs, and the CLI's own
project memory folder, whose name is derived from the repository path rather
than the repository identity. Syncing the repo to a second machine carries the
code and leaves all of that behind.

Handing a session's context to the other machine would let me re-brief it. It
would not tell either machine which copy of the database is authoritative, and
that is the failure I actually care about. Work on both and the two copies
drift apart with nothing able to reconcile them, so someone's hours get thrown
away. A git conflict tells you exactly what disagrees and asks you to choose.
Two databases just disagree.

Two smaller observations from the same episode.

A kill notice is not proof. Background jobs reported killed for low memory kept
running on Windows, and I ended up with three copies of the same loop hitting
one rate-limited upstream API before I checked the process table instead of
trusting the notifications. A per-machine view of what a session is actually
running would have caught that in seconds.

Shared upstream limits make a second machine slower rather than faster. Both
machines would have reached the same API through the same credentials against
the same per-address rate limit, so the second one buys no throughput.

So alongside session continuity, I would value a claim on the project, held by
one machine at a time and visible to any other session that opens the same
repository. It does not need to be enforced. A warning that says another machine
holds this project, last heartbeat four minutes ago, would have prevented every
bad outcome in my case.

@datalifenyc — the line you dropped in passing is the one I would put at the top.

the CLI's own project memory folder, whose name is derived from the repository path rather than the repository identity

That derivation fails inside a single machine too, not only across two. The store
name is the absolute path with every non-alphanumeric character replaced by a
single -, so the mapping is not injective: two sibling folders whose names
differ but happen to have the same length collapse into one store. Mine did. Six
unrelated client projects under the same parent — all four-character Korean names
— resolved to D--Project-Life-Dev-------------.

Measured on my machine after I noticed:

• 55 days of accumulation before I saw it (oldest memory 2026-07-20, caught

2026-09-13). MEMORY.md is auto-loaded at session start, so for 55 days each
client's session opened with five other clients' notes presented as its own.

• 26 transcripts, 437 MB pooled in that one directory — which is also why my

per-project usage accounting had been wrong.

• 88 memory files had to be re-assigned by hand. Names were not enough: six

were named for the wrong project (kta-fee-system was written by a different
client's session), so ownership had to be re-derived from originSessionId →
that session's cwd, and the remainder judged by each project's own session.

• ~35 hours and 36 instructions from first noticing to done — and none of it

was fixing anything. It was working around it.

On your claim/lease idea: I wanted the same thing one scope smaller. You want one
machine to hold a project. I needed one project to hold its own store, and had
no way to see that six were sharing one. No warning, no log line, nothing in
/status. The cheapest version of what you describe would have caught mine too —
the store recording the absolute path it was created for, and saying so when a
different path opens it.

The workaround that exists (autoMemoryDirectory) isolates memory only. My
437 MB of transcripts still pool in the colliding directory today. Filed with a
controlled repro as #93960.

the self-authored state tag catches the case you already know is shaky (the 'not yet verified' line worked precisely because you knew you hadn't checked). but the wrong '86' would have gone out stamped 'verified' too, since that failure was confidence, not doubt. a tag written by the same narrator inherits the same blind spot it's meant to close. only the host-derived stamp in your point 3 actually catches the confident-and-wrong class; point 1 alone catches only the already-doubted one.

@datalifenyc — the line you dropped in passing is the one I would put at the top. > the CLI's own project memory folder, whose name is derived from the repository > path rather than the repository identity That derivation fails inside a single machine too, not only across two. The store name is the absolute path with every non-alphanumeric character replaced by a single -, so the mapping is not injective: two sibling folders whose names differ but happen to have the same length collapse into one store. Mine did. Six unrelated client projects under the same parent — all four-character Korean names — resolved to D--Project-Life-Dev-------------. Measured on my machine after I noticed: 55 days of accumulation before I saw it (oldest memory 2026-07-20, caught 2026-09-13). MEMORY.md is auto-loaded at session start, so for 55 days each client's session opened with five other clients' notes presented as its own. 26 transcripts, 437 MB pooled in that one directory — which is also why my per-project usage accounting had been wrong. 88 memory files had to be re-assigned by hand. Names were not enough: six were named for the wrong project (kta-fee-system was written by a different client's session), so ownership had to be re-derived from originSessionId → that session's cwd, and the remainder judged by each project's own session. ~35 hours and 36 instructions from first noticing to done — and none of it was fixing anything. It was working around it. On your claim/lease idea: I wanted the same thing one scope smaller. You want one machine to hold a project. I needed one _project_ to hold its own store, and had no way to see that six were sharing one. No warning, no log line, nothing in /status. The cheapest version of what you describe would have caught mine too — the store recording the absolute path it was created for, and saying so when a different path opens it. The workaround that exists (autoMemoryDirectory) isolates memory only. My 437 MB of transcripts still pool in the colliding directory today. Filed with a controlled repro as #93960.

@intermap74 Good point.

Your collision doesn't happen to me, since my paths are ASCII and
the alphanumerics survive the substitution. The naming bites me the other way
instead: the store is the path, so renaming or moving the project directory
gives me a fresh store and the old memory is just absent. I haven't done that
by accident yet. I'm only sure it happens because the directory name is my
absolute path with the punctuation swapped for dashes.

So I'd drop the lease I floated in favour of what you suggested. Recording what
the store was created for is smaller and catches more: your case when a
different path opens it, mine when a different host does.

One thing I'd add to it. Six projects sharing a store went unseen for 55 days,
which is a reporting gap sitting on top of the naming one. /status could
print the store directory in use and the path that created it. That's two lines
of output, no design change, and it would have shown you the problem the first
day instead of the fifty-fifth.

Agreed — and your rename case is the same defect seen from the other side. The store name is a pure function of the absolute path: two paths that flatten to the same string share one store (my case), and one project whose path changes gets a fresh one (yours). Neither direction needs a second machine. Identity is the missing half in both.

On your /status lines, I would make the second one a comparison rather than a fact. My store had been created by a different project than the one opening it, five times over, so "created for <path>" printed next to "opened from <path>" would have been a visible mismatch on day one, and nobody would need to know what the encoding does to read it. A single warning line when the two differ would carry the whole thing, and it needs no new subsystem.

I would also put the reporting gap ahead of the naming one for whoever picks this up. Unpicking the collision took about 35 hours. Not being able to see it cost 55 days, with six clients' notes loading into each other's sessions the entire time.

Small update from the claude-handoff side (https://github.com/NeoAcar/claude-handoff), since several tools here move the real JSONL: on Claude Code 2.1.x the transcript now includes the account email and organization UUID (session_context and credential_org attachments, plus a rendered copy of the email). Worth checking if your tool shares transcripts with teammates or commits them.

0.2.1 scrubs both by default, on top of secret redaction and path rewriting, and bundles the new tool-results/ files so path references in the transcript don't dangle after import. Round-trip re-verified on 2.1.288 (Linux).

One gap worth designing for: a handoff file can be wrong. A session that ran out of context may write "done" for work it never committed. What has worked for me is citing a commit hash or file path for every "done" line, and having the next session check those exist before it trusts the file. Disclosure: I maintain Succession, a free MIT plugin that writes the handoff at close, hands it back at session start, and runs that check: https://github.com/thecontinuitylayer/succession