Session handoff (carry a long chat into a fresh session)
Session handoff turns one long, cluttered session into a fresh one that is already caught up: same project, folder and branch, carrying a summary that keeps the conclusions and lists the dead ends as things not to retry. One click in a session's overflow menu does it, and the old session is left completely untouched.
On this page
What it is
Session handoff turns one long, cluttered session into a fresh session that is already caught up — same project, same folder, same branch, with a link back to the one it came from. One click on "Hand off to a fresh Omniscio session…" in a session's ⋯ menu does the whole thing.
Here is the problem it solves. A session you have been working in for hours is carrying everything that happened in it: the three approaches you tried and threw away, the files you opened that turned out to be irrelevant, the error messages you already fixed, and the reasoning you built on an assumption that changed an hour later. Omniscio's AI reads all of it, every turn, and it cannot tell which parts you have mentally discarded. To it, a dead end you abandoned at 2pm looks exactly as live as the thing you are actually doing now.
A handoff is an edit. It writes a summary that keeps the conclusions and drops the search, then starts a new session holding that summary. The old session is not deleted, archived, stopped, or changed in any way — it stays right where it is in your sidebar, so if the handoff turns out to have missed something you can go straight back and read it.
Nothing happens automatically, and nothing is ever spent without a click. Omniscio can show a short note in the chat when a session gets long, suggesting a handoff — that proactive note is off by default; you can turn it on in Settings → Sessions (see below). The note is only a suggestion: showing it costs nothing at all — no summary is written, no file is saved, no new session is started. Only the button on the note, and then the Hand off button in the box that opens, spends anything. The ⋯ menu handoff is always available regardless of this setting.
The same button also appears at the one place a session used to be a dead end. When a session's context fills to the point that Omniscio's automatic recovery tries a few times and still cannot get an answer out, it gives up rather than burn money in a loop — and it used to leave a plain sentence there with no way forward. Now that give-up note carries the same Hand off to a new chat → button too, so a wedged session is never a dead end: one click summarizes it and continues in a fresh one. Showing that button still costs nothing; only clicking it spends.
Handoff vs. compaction — they are not the same thing
Claude's own answer to a full session is compaction: it writes a summary of the conversation so far and swaps the old turns out, keeping one session alive. That works, but it carries everything forward in condensed form — the dead ends come along with the useful parts.
| Compaction (automatic) | Handoff (you choose it) | |
|---|---|---|
| When | Automatically, when the session is nearly full | Only when you click |
| Result | The same session, with its history condensed | A new session, linked to the old one |
| Dead ends | Carried forward, condensed | Deliberately listed as "do not retry" |
| The old chat | Replaced in place | Left completely untouched |
| Cost | Included in the session | Free on a Claude plan, otherwise one small paid summary call |
Handing off does not replace compaction. A session you never hand off still compacts exactly as it does today. See Compaction Summary.
Where to find it
How to use it
Open a session's ⋯ menu (top right of the session) and choose "Hand off to a fresh Omniscio session…". It sits right next to the Context NN% row, because the number in that row is what makes the action worth taking.
You will occasionally see two other versions of that item instead:
- "Already handed off: open the new Omniscio session" — this session has been handed off once already and the new session actually started. Omniscio only does it once per session, so the item takes you to the session it created instead of making a second one.
- Greyed out — either the session has no conversation yet (there is nothing to summarize), or it is already at the end of a long chain of handoffs. Hover it and the tooltip says which.
A handoff whose new session never started does not count as done — you get "Hand off to a fresh Omniscio session…" back, even if you have since archived the failed session, so the retry is always available.
Read the box that opens. It tells you, before anything is spent:
- How much context the session is using, e.g. "Using 220k tokens of context (22% of a 1M window)". If the session has not run since you last started Omniscio, this says unknown — that is normal, and the handoff still works.
- What Omniscio will do, as a numbered list.
- Both places it writes, spelled out in full.
- What the summary call costs, also printed on the button itself. If you are signed in with a Claude subscription, Omniscio runs the summary on that plan, the same way it runs your sessions, and the box says so instead of naming a price. Signed in with an API key instead, it estimates the charge in dollars.
Optionally tell it what to emphasize. There is a free-text box: "Anything Omniscio should emphasize?" Whatever you type is folded into the summary request — for example "keep the decision about the database, drop the CSS detour". Leave it blank and the standard summary is written.
Optionally tick "Also append a short entry to this project's Auto Context." Off by default. Ticked, Omniscio adds a ten-ish-line dated entry to a file every future session in this project reads. Useful for a running project history; it does cost a little context in every session from then on, which is why it is off unless you ask. Whichever way you leave it is remembered for the next handoff in this project — but only if you actually go through with the handoff. Ticking it and then cancelling changes nothing.
Click Hand off. That is the only point where anything is spent. Omniscio writes the summary, saves it, starts the new session, and takes you to it. The new session opens with a pinned "Spawned by …" note at the top pointing back at the parent, and the old session gets a "Handed off to → …" note pointing forward.
If the box says the word-for-word tail did not fit, read that line. It means the new session has the summary but not the last stretch of the conversation verbatim, because there was no room for both. If a recent detail matters, paste it in yourself once the new session opens. Omniscio always tells you when this happens — it never quietly drops it.
An agent-requested handoff never takes over your screen
A handoff can also be requested by an agent rather than clicked by you. By
default it just happens — a session that fills up hands itself off and keeps
working, with no approval stop in between, because a handoff only continues work
you already set in motion. If you would rather review each one first, turn on
Session handoff under Settings → CLI Control → approval toggles
(requireApprovalForCliSessionHandoff); with that on, agent-requested handoffs
queue in your inbox as approvals again.
Either way, an agent-started handoff behaves differently from your own click in exactly one way: it never moves your view.
- You clicked Hand off yourself → Omniscio takes you straight to the new session, because you asked for it and that is where you want to be.
- An agent started the handoff (instantly, or after your approval when the toggle is on) → the new session appears quietly in the sidebar and your screen stays exactly where it was.
This matters most when you approve a batch at once. Approving fifty queued handoffs used to drag you into fifty new sessions one after another; now the whole batch lands silently. You still get the confirmation for the batch, each request visibly flips to approved, every new session shows up in the sidebar, and each original session carries its "Handed off to → …" note pointing at its successor — so nothing is hidden, it just does not interrupt you.
The same rule covers every session an approval can start, not only handoffs — a re-run from an edited message, or a "let's get you unstuck" coaching session. If one of them ever genuinely needs your attention, Omniscio shows a toast you can click, never a jump you did not ask for.
Turning the suggestion note on or off, or moving when it appears
The proactive note is off by default — turn it on (or tune when it appears) in either of two places, same two settings:
- Settings → Sessions → Advanced, next to the 75% / 90% context warnings — which are now off by default too, so a fresh install gets no context nag of either kind.
- Right on a note itself (once you have switched it on) — the ⋯ button at the end of the note line (or right-click the note) opens a small popover that explains what the note is and carries both settings.
The settings are: whether to suggest at all, and how the size is chosen — by default Automatic, which scales the trigger to the model (see below). Turn Automatic off to pin your own exact token number instead. Changes affect future notes only, so the one already on screen stays put. Pinning a very high custom number is a way to mute the suggestion without switching it off — and the ⋯ menu item is always there regardless of the note.
How it behaves
How the size is chosen (it scales with the model)
By default the trigger is Automatic: Omniscio sets it to 75% of the model's own context window, as a real token count. So a session on a 1M-window model (Opus 4.8, Sonnet 5, Fable 5) is nudged at 750,000 tokens, a 2M model at 1.5M, and an older 200k model at 150,000 — the very number the feature used to use for everyone. You can turn Automatic off and pin an exact number if you prefer.
Why it scales, and why it is still a real token count (not a "% full" gauge). The thing that degrades an AI's answers is how long its input is, not how full its window is — but how long is too long is larger for a larger, more capable model. A single frozen 150,000 was the right number back when every model held 200,000 tokens (0.75 × 200k), and it silently became far too eager when windows grew to 1,000,000: a "start fresh?" nudge at 150k on a 1M model fires at 15% full, which is absurdly early. Scaling to 75% of each model's window fixes that while keeping the trigger an absolute, auditable token count — a percentage is the right gauge for "will this compact soon?" but the wrong thing to show here, so you always see the real tokens.
Per-model tuning where we have data. A model whose answer quality is known to degrade earlier gets a hand-tuned override instead of a flat 75%. DeepSeek is the first: measured retrieval already slips well before its 1M window is full, so its suggestion is pinned to 750,000 — kept equal to its compaction point — rather than the flat 75% default, which would resolve to 786,432 and fire after compaction had already happened. Every other model uses the 75% rule until there is a reason not to.
What the number counts. It is context in use, not the length of your conversation. It includes the system prompt, the tool and skill definitions, and any project documents folded into the session, alongside the actual turns. That is the correct quantity, because the model reads all of it — and it means a heavier setup reaches the threshold sooner, which is true and worth seeing rather than hiding. The wording is always "using … of context", never "this conversation is …", for exactly that reason.
The three-dead-ends rule of thumb
A size threshold is only half the signal. The other half you have to judge yourself:
Once a session has produced three genuinely rejected approaches to the same problem, consolidating usually beats continuing.
By then the context is holding three plausible-looking wrong paths that the model cannot tell apart from the live one, and the cost of re-deriving from a clean summary has dropped below the cost of reasoning around the wreckage. Three is also Omniscio's existing number for "this isn't working" in two unrelated places, both of which arrived at 3 independently.
This is deliberately not automated, and it is not going to be. A "dead end" is a judgment about intent — telling abandoned because it was wrong apart from parked to come back to apart from worked but looked messy means reading what you meant. Every cheap stand-in available (turn count, turns that ended in an error, stall-recovery firings, tool-call churn) misfires on ordinary hard work, and a false alarm here would nag you toward paid new sessions you did not need. A confident-looking detector that is wrong a third of the time is worse than no detector, so the number lives here and in the note's tooltip as something you apply, not something the app computes.
Limitations worth knowing
- The note needs a session that has run since Omniscio last started. Context size is only ever held in memory — it is never saved to disk — so a session that has not streamed anything since the app launched has no token count for Omniscio to compare against the threshold. Practical consequence: a session that was already past 150k when you restarted Omniscio will not get a suggestion. The box shows "unknown" for its size, and the ⋯ menu item still works normally — this costs you a nudge, not the feature.
- Ended and paused sessions have no live number for the same reason. You can still hand them off; the summary is read from the database, not from a running process.
- One handoff per session. Deliberate. If you want to split work three ways, hand off, then hand off again from the successor.
- A session that is still working can be handed off. The successor takes the worktree over — Omniscio moves the folder's recorded owner to the new session — so you do not have to stop a long-running session first. The old session keeps running, though, so stop it once the handoff has launched: two sessions in one folder means two writers on the same files.
- A worktree that is reserved cannot be taken over. When the old session's worktree is currently reserved by the worktree pool, Omniscio checks that before spending anything on the summary. The successor then starts in the project's own folder instead, and the saved transcript goes there too, not into the reserved worktree. A built-in project such as the default Claude project starts in its real folder.
- Same project only. The successor lands in the same project. Moving work between projects is a separate thing.
- A session running on one of your SSH remotes stays on that remote. The successor is started on the same machine, in the same folder the original was working in — not in the copy of the project on this computer — and it is told the full transcript lives on the machine running Omniscio rather than being pointed at a path it could never open. See When a handoff can't start at all below for the two cases that are refused instead.
- Handing off to a non-Claude engine — the sizing is settled, the rest is not. The summary is database-based, so it works everywhere. The word-for-word tail is measured against the successor's window, including when you pick a different provider without naming a model — a case that used to measure against the window of the session you are leaving, and so could hand a smaller-window vendor far more text than it can hold. A provider Omniscio has no default model for now falls back to a small, safe budget rather than to your global model. What remains unverified is the rest of the non-Claude path end to end, not the sizing.
When a handoff summary fails — what each message means
The handoff box names the actual reason, in your language, and says what to do. When the paid fallback also runs and also fails, the message still names the subscription run's reason, because that is the one you can act on.
| The message starts with | What happened | What to do |
|---|---|---|
| "A handoff summary needs a working Claude sign-in or an Anthropic API key." | No Claude subscription login is available, and no API key is set up, so there was nothing to run the summary on. | Sign in or add a key in Settings → Accounts, then hand off again. |
| "Claude rejected your sign-in…" | Claude refused the login the summary ran on — for example, it was revoked or expired. | Sign in again in Settings → Accounts, then retry. |
| "Your Claude plan's usage limit is reached…" | The subscription hit its usage cap. | Retry after the limit resets. |
| "This conversation is too long for Claude to summarize in one pass…" | Claude refused the request as too large. | Start a fresh session by hand and paste in what matters; retrying the same session will not help. |
| "Claude is overloaded or unreachable right now…" | Claude's service was busy or could not be reached. | Retry in a few minutes. |
| "Writing the handoff summary took too long…" | The summary ran past Omniscio's time limit and was stopped. | Retry, or hand off a shorter conversation. |
| "Couldn't write the handoff summary." | Something else went wrong. | Retry once; if it keeps happening, report it. Omniscio already sends this one to its crash reports. |
The "too long", "took too long" and "something else" cases are reported to Omniscio's crash reporting automatically, each under its own name. A sign-in, usage-limit or busy-service failure is logged but not reported as a crash, because it is not a fault in the app.
When a handoff can't start at all
Two handoffs are refused before anything is spent — no summary is written, and the session is not marked as handed off — because neither could work wherever the successor was sent:
| The message starts with | What happened | What to do |
|---|---|---|
| "Sessions running in the cloud can't be handed off…" | The session runs on a cloud machine. A successor there would need its own machine and its own sign-in, which a handoff does not set up, so the new session could not connect. | Start a fresh session instead. |
| "That engine only runs on this computer…" | You picked an engine for the successor that cannot run on a remote machine, so it cannot continue a session that runs on one. | Choose an engine that runs on remotes, or hand off a session that runs on this computer. |
Both leave the original session exactly as it was — including its one handoff per session limit — so you can pick a different engine and try again straight away.
Related
- Context usage warnings (75% and 90%) — the older percentage-based warnings. They are also off by default now, so no context nag of either kind reaches a fresh install; the handoff note is still a separate row with its own separate setting, sized per model in absolute tokens for the reason in How the size is chosen above.
- Compaction Summary — what Claude does automatically when a session fills up, and how to read the summary it writes. Handoff is the deliberate alternative to letting that happen.
- Session provenance — the "Spawned by …" note pinned at the top of the successor is the same mechanism that traces any spawned session back to its origin.
- Keep my computer smooth under load — governs how often Omniscio takes an authoritative context reading; the handoff note forces a fresh reading once a session is near the threshold, so it never fires off a stale number.
Last verified 2026-11-03