Session isolation
How to give a session its own private copy of your project instead of letting it edit your real folder — where the switches live, what that copy contains and what it leaves behind, how the work comes back when the session ends, and what happens when a copy cannot be made.
On this page
What it is
Normally a session runs in your project folder, so everything the agent reads and edits happens in your real checkout. Isolation gives a session its own private copy of the project instead: Omniscio creates a git worktree — a second checkout of the same repository, on its own branch — and runs the session there. Your project folder is untouched while the agent works, and two sessions running side by side can each edit the same file without overwriting one another.
That is the whole point of it: parallel sessions on one project. Without isolation, a second session editing the same files as the first is a race you lose silently.
Where to find it
| Where | What it sets |
|---|---|
| Shift+click the + button in the Sessions panel | This one session — start it in its own copy |
| A not-yet-started session's ⋯ menu → Worktree Session | This one session — turn its own copy on or off |
| Edit Project → More options → Isolate new sessions | Every new session in that project |
| Settings → Sessions → Work on separate copies (app-wide) | The default for projects you have not set yourself |
All of them are off by default. What you pick applies to sessions you start next — never to the ones already running. To override it for a single session, Shift+click the + button in the Sessions panel to start that session in its own copy, or open the ⋯ menu of a session that has not started yet and toggle Worktree Session. A session that has already started cannot be switched — isolation is chosen before it begins.
How it behaves
What changes and when
Two extras worth knowing:
- A session that is already running keeps running where it is. Isolation applies at the moment a session starts, never retroactively.
- Sessions on an engine whose tools run outside Claude Code's guardrail hooks are isolated by default — Gemini, Grok, Antigravity, OpenCode, Hermes, Pi, Kimi Code and DeepSeek Harness. For those engines the worktree is the only structural barrier standing between the agent and your real checkout. How much each one asks you first varies, and asking is not a guardrail: the project and app-wide defaults cannot turn this off, but an explicit per-session choice still can, and a folder without git always runs in place.
Where the copy lives
By default, in a <your-project>-worktrees folder beside the project folder — not inside it, so your repo stays clean and repo-wide searches stay fast. Each session gets its own subfolder there.
What is inside the copy
- Your tracked files, checked out on a new branch created for that session.
- Your
.envfiles from the project root (.env,.env.local, and similar) are copied across, because the agent needs them and git does not carry them. - Anything git does not track is not there. Local scratch files, build output, screenshots you saved into the folder, a private config you never committed — none of it is copied. If the session needs a file git does not know about, commit it or hand it to the session explicitly.
- Dependencies are prepared in the background once the folder appears. For the first moments a large project may not yet have its
node_modulesor other installed packages, so the agent's first build or test command can need to wait. A small area (a largeaudit-reports-style folder, for example) may be left out of the checkout on disk to save space while still being tracked by git. - If preparing those dependencies fails, the session keeps what it had. A re-prepare that goes wrong puts back the shared dependency folder it was replacing rather than leaving the session with none, and the session is told what failed and what to do about it — including, when the cause is a lockfile that disagrees with the project's own package list, which entry disagrees. That folder was built for a different lockfile than the session's branch carries, so its first gated command still asks for a repair; the difference is that the session is left usable in the meantime, and a failure that cannot be fixed by trying again says so instead of telling you to re-run it.
- Heavy per-session cost. Each isolated session is a real checkout with its own branch and its own dependencies, so it uses disk. That is the trade for two sessions not fighting over one folder.
What happens to your work
Work in an isolated session is committed on the session's own branch. When the session is archived, Omniscio merges that branch back into your project's branch — but only while the in-app auto-lander (the background lander the Dev Pipeline uses) is armed, which is the Auto-lander master switch in Settings → PR Merge Queue (the Dev Pipeline panel's Setup tab shows the same switch). It ships disarmed, so on a default install the archive merge-back is skipped: the branch is kept exactly where it is, and nothing is thrown away.
- If the merge is clean, the work lands on your project's current branch and the copy is finished with.
- If the branch conflicts, Omniscio starts a short, single-purpose resolver session to settle the conflict and then lands the branch. That resolver is a real session — it is billed like any other and spends your account's usage for the turns it takes to work the conflict out, so a conflicting archive costs a little. It runs only as part of the auto-lander's merge-back, never on its own initiative, and never at all while the lander is disarmed (the default). It is capped at two attempts: if the branch conflicts again after that, it gives up rather than running forever.
- If the merge fails outright, the branch is left untouched. Nothing is thrown away in any of these cases — the branch keeps every commit.
- If the merge-back was skipped — the default while the auto-lander is disarmed — the work is still there and is yours to land: the session's branch is untouched and is named
session/<session-id>-<slug>. Find it withgit branch --list 'session/*'in your project, which still lists it after the copy's folder has been reclaimed. Merge that branch into your project's branch with your usual git tooling, or arm the in-app auto-lander (in the Dev Pipeline panel) so Omniscio lands isolated branches for you. A merge-back you ask for by hand — Retry Merge (POST /session/:id/retry-merge) — is never blocked by the auto-lander switch. - If a session is archived while work is still uncommitted, that work is committed to the branch before anything else happens, so it survives too.
Getting rid of the copies
Copies are cleaned up for you, and only when it is safe:
- Finished copies are removed by the worktree reaper. Every five minutes the worktree reaper looks for copies whose session is archived or ended, or whose branch has landed. A copy whose session has been gone for about two hours has its folder reclaimed automatically while its branch is kept: any unsaved work is saved first and the reaper never deletes a branch, so the work is still recoverable later. The wait is the shared 2 hours since the session last did anything, and a session still working in a copy keeps it. It is on by default, on every platform; its switch is Settings → Performance → Remove finished work areas automatically. There is no separate cleanup tool to turn on.
- An idle session's copy is taken back after six hours. Leave a session untouched — no turn
running, no message waiting, nothing queued, nothing pinned — for six hours and its folder is
released back into the reuse pool: any uncommitted work is saved beside the branch first, and the
next time the session runs it simply gets a fresh copy of its own. The session is never deleted and
its branch keeps every commit, so nothing is lost. This idle-release is on by default, and it
has no on-screen switch: turn it off from the command line with the
worktreeIdleLeaseEnabledsetting and an idle session keeps its copy indefinitely. - Anything still in use, locked, or pinned is left alone.
- To keep a copy for good, mark it. A copy whose branch description carries a keep note is never removed — any free text that says not to delete it, such as "do not delete this worktree", "keep this branch", "never reap" or "keep it alive". The same words placed in the copy's own folder name protect it too. That veto is absolute: the worktree reaper and the six-hour idle release skip a copy that carries it. (An agent can set the note — the words are matched, not a special field — so a session can protect its own copy when it matters.)
- Work that git ignores is rescued, not lost. Before a landed copy is removed, anything it
holds that git does not track — a scratch file, a saved report, a build artifact — is moved to
Omniscio's rescue folder (
~/.amc/worktree-rescue) rather than deleted with the folder, so even gitignored work survives the cleanup. (A copy that still holds such work is kept rather than reaped, until it can be rescued.) The rescue folder stores each distinct file's content once: a copy whose bytes already exist in it is linked to that copy instead of written again, so the same file saved a dozen times costs one file's worth of disk. Nothing is ever removed for being old or large — only a proven byte-for-byte duplicate is folded — and the folder's total and unique size are reported on the disk readout. - A removed copy is usually recycled, not deleted. Omniscio keeps a pool of around 220 ready-made copy folders per repository, reused from copies that have already been retired, so a new isolated session gets an instantly-ready folder instead of a fresh checkout. The pool is on by default and only ever folds away folders whose work has already landed; turning the pool off makes every new copy a fresh checkout again.
- An item the cleanup cannot remove brings an inbox card, A worktree folder won't delete. If it is something Omniscio has no record of putting in its cleanup folders — a stray file or folder another program or agent left there — the card says so, and Omniscio never deletes it without you: Start session on the card opens an agent that shows you each item and changes nothing until you choose keep or delete. A folder Omniscio retired itself that won't go usually has a file locked by another program.
When a copy cannot be created
Isolation can fail — a disk full, a repo the machine cannot write to, a box under heavy load. Omniscio checks free space before it places or makes a copy, so a nearly-full drive never gets one silently: creating a copy is refused below 2 GB free on the destination (or the repo's own drive); a new isolated session is held while its drive is below 8 GB free and declined below 2 GB; and choosing where copies live skips a worktree folder under 10 GB free and a repo drive under 40 GB free (routing to another location instead). Two settings decide what happens when no copy can be made at all, and both are off by default:
- Require isolation for every session stops the session with an error instead of letting it fall back into your main project folder — the fail-closed choice.
- Default isolation folder gives it somewhere safe to run instead. It is only consulted while Require isolation for every session is on: instead of stopping, Omniscio copies your source into a subfolder of this path and the session runs there, never in your real checkout. Left empty (the default), a session that cannot be isolated stops with an error.
- Fallback copies are pruned automatically. Omniscio records each copy it creates in that folder and, when a later fallback session is created, deletes recorded copies older than 24 hours and keeps only the newest three — including any uncommitted work inside them. Subfolders Omniscio did not create are never touched, but a dedicated folder is still the tidiest choice.
Good to know
- Isolation needs a real git repository. A folder without git, or a built-in project like Skills or Recipes, always runs in place.
- The Worktree Session item appears only for an engine that can actually run in a copy. Engines that always work in your main project folder do not offer it, rather than offering a switch that changes nothing.
- What that item shows is what the session will really do, including the engines that isolate by default: for one of those the item is already ticked when you open the menu, and a single click turns its copy off.
- Worktrees are a git feature, not an Omniscio-only trick:
git worktree listin your project shows every copy that exists, and each one is on its own branch. - Turning isolation off for a session is a real choice, not a failure — a quick one-off change to a file you are watching is often simpler when the agent edits your folder directly.
- A session whose copy was handed on to other work moves to a fresh copy when it restarts. Omniscio reuses idle copies — the six-hour idle release above is what hands a copy back to the pool — so a message, a reply, an automatic wake or the Restart button never restarts such a session inside the old copy, and never in your main project folder either. Instead it gets a new copy of its own — on its own branch when that branch is free, otherwise on a new branch from master — shows a line saying it is moving, and its agent is told where it now works. Its conversation carries on.
- When the move itself cannot be made, the session stops and waits for you. A move can only fail for a reason only you can clear — a full drive, or a copy that is no longer this session's own and whose branch cannot be settled. The session then stops with a message naming its branch and sits in Interrupted until you restart it; Omniscio does not keep retrying a move it has already decided it cannot make, and nothing is thrown away in the meantime.
- A session whose copy was removed — reclaimed by the cleanup above — is the one exception: with no copy left to move it to, such a session restarts in your project folder itself. Its branch still holds its work, so nothing is lost.
Related
The Projects sidebar explains the panel the + button and the per-project options live in. The copies nobody is using any more, and the worktree reaper that removes finished copies, are covered on this page.
Last verified 2026-11-15