--- title: Session isolation --- # Session isolation ## 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 | | --------------------------------------------------------- | ------------------------------------------------------------------ | | **Launch menu** — hold the **+** button in the Sessions panel | This one session (the **Isolate** toggle) | | **Edit Project → More options → Isolate new sessions** | Every new session in that project | | **Start new sessions in their own workspace** (app-wide) | The default for projects you have not set yourself | All of them are **off by default**. A session can always be flipped at launch even when the project's default says otherwise, and the change applies to sessions you start next — never to the ones already running. ## 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 that **auto-approves every tool call** are isolated by default regardless of these settings. For those engines the worktree is the only thing standing between the agent and your real checkout, so it is not left optional. ### Where the copy lives By default, in a **`-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. You can change where they go, per project: **right-click the project → Edit Project → More options → Worktree location**. Pick a folder on a drive with room for build output and dependencies — that is the whole reason the row exists. The choice is stored per machine, in a git-ignored file, so it never travels to anyone else who uses the repo. ### What is inside the copy - **Your tracked files**, checked out on a new branch created for that session. - **Your `.env` files** 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_modules` or other installed packages, so the agent's first build or test command can need to wait. A small area (a large `audit-reports`-style folder, for example) may be left out of the checkout on disk to save space while still being tracked by git. - **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, and Omniscio merges that branch back into your project's branch **when the session is archived** — you do not have to remember to do it. - **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 automatically. It is capped: if it conflicts again after that, it stops and tells you rather than running forever. - **If the merge fails outright**, you get an inbox card saying your work is preserved, and a **Retry Merge** action on the session's worktree badge. Nothing is thrown away in any of these cases — the branch keeps every commit. - 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: - The **in-app worktree cleanup** (Settings → Performance → **Run automatic worktree cleanup**) reaps copies whose work has already landed. A second, session-aware cleanup and the bundled **`/worktree-cleanup`** skill do the same from the Dev Pipeline side — see [Worktree Cleanup Skill](worktree-cleanup-skill.md), which never loses work and always reports what it kept and why. - An **abandoned** copy — one whose session has been gone for a day — has its folder reclaimed automatically while its branch is kept, so the work is still recoverable later. See [Orphaned Workspace Archive](orphan-worktree-archive.md). - Anything still in use, locked, or pinned is left alone. - 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. Two settings decide what happens then, and both are off by default: - **Require worktree isolation** stops the session with an error instead of letting it fall back into your main project folder. - **Fallback folder for a failed isolated workspace** gives it somewhere safe to run instead: Omniscio copies your source there and the session runs in that copy rather than in your real checkout. ### 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. - Worktrees are a git feature, not an Omniscio-only trick: `git worktree list` in 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, 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. Only if the move itself fails (for example, a full drive) does it stop with a message naming its branch; restarting it tries the move again. ## Related [Worktree Cleanup Skill](worktree-cleanup-skill.md) covers reaping copies whose work has already landed, and [Orphaned Workspace Archive](orphan-worktree-archive.md) covers what happens to the copies nobody is using any more. [The Projects sidebar](projects-sidebar.md) explains the panel the **+** button and the per-project options live in.