> ## Documentation Index > Fetch the complete documentation index at: https://continuum-three-olive.vercel.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Sessions > Spawning, resuming, and organizing agent sessions across repos, worktrees, and remote hosts. Sessions are the unit of work in Continuum. Each session ties an agent to a working directory, runs in a daemon-managed runtime, and persists its transcript — for the CLI-backed providers, as a JSONL file under the provider's own session directory (`~/.claude/projects/` for Claude, `~/.codex/sessions/` for Codex). The Code sidebar shows **only sessions Continuum spawned** ("managed" sessions), grouped by project. It does not list arbitrary CLI sessions you started elsewhere. ## Starting a session The new-session surface is a **floating composer box**. Open it from `Cmd+N`, the **New session** button pinned to the bottom of the Code sidebar, or the per-repo `+`. It floats over your current session behind a dimmed backdrop rather than replacing it — click the backdrop to dismiss, and nothing about the session underneath changes. Each open starts a fresh, empty composer. Pressing send spawns the agent and drops you into the new session. Older builds opened a modal **New Session sheet**, and worktree mode was chosen by ⌥-clicking the `+`. Both are gone: the floating box is what `+` and `Cmd+N` open, and it carries every spawn control itself. Directly under the composer box sits a row of borderless ghost chips that configures the spawn: | Chip | What it sets | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Repo** | Which project the session runs in | | **Worktree / Local** | The checkout this session gets — one click flips it, no dropdown | | **Account** | Which signed-in account to bill against. Every provider supports [multiple accounts](/docs/features/multi-account); the chip appears once you have two or more signed in on the selected one | | **Device** | Which machine runs the session | The **Device** menu lists **This Mac**, **Continuum Cloud** (when your account is entitled to [hosted inference](/docs/features/hosted-inference)), and every [execution host](/docs/features/remote-devices) you've registered — a second Mac, a Windows or Linux desktop, a VPS, a Tailscale device, a BYOC runner. **Add device…** at the bottom jumps to **Settings → Devices**. The composer's own chip row — the one inside the box, alongside Send — carries the rest: the model picker (which also selects the provider), reasoning effort, and the **Plan / Code** permission pill. ### Providers and models The model picker is a vertical rail of providers plus **Auto** (automatic routing) and **Starred** (your favourites across every provider): **Claude · Codex · Gemini (Antigravity) · Cursor · OpenCode Go · OpenRouter · Z.ai Coding · Grok · Continuum** Each rail is populated from that provider's live catalog, so it reflects what you're actually signed in to rather than a hardcoded list. OpenRouter and [Z.ai Coding](/docs/providers/zai) ride the same OpenCode connector as OpenCode Go but keep their own credentials, catalog, and spend column. Continuum is the [hosted](/docs/features/hosted-inference) lane — no local CLI involved — and splits into free and frontier sections. **Auto** is not a model. Pick it and Continuum assigns a planner, an executor, and a cross-provider verifier from the providers you have connected, then runs plan → your approval → execute → verify, stamping each stage with the model that actually ran it. It's a choice you make when the session starts, not something that reroutes a session already in flight; a running session keeps the model you gave it. See [Auto model routing](/docs/providers/overview#auto-model-routing). Reasoning effort runs **minimal → low → medium → high → xhigh → max**, and the effort chip only appears for models that accept it. `⌘⌥E` cycles up that ramp and `⌘⌥⇧E` cycles down. Each CLI takes a different slice of it, so the tray offers only the rungs the selected provider actually honors; switching providers clamps a carried-over effort to the nearest supported rung instead of silently downgrading it at spawn time. Claude adds one rung above the ramp — [Ultracode](/docs/providers/claude) — offered only as an explicit choice, never as something the cycle lands on. ## Local vs. Worktree mode **Local** runs the agent in the repo's primary checkout — the same directory the raw CLI would use. **Worktree** creates or reuses a `git worktree` at `~/Clawdmeter/workspaces//`, so the agent works on its own branch without touching your main checkout. You pick this per session with the **Worktree / Local** chip. It's seeded from a default that resolves in two layers: a global default in **Settings → Workspaces**, overridden by an explicit per-repo setting (also in **Settings → Workspaces**). Your pick applies to that one spawn and deliberately does not write back to the per-repo default. Once a session is running its mode is fixed. The composer then shows a read-only badge of the session's mode rather than an editable chip. ### Session names and branch slugs The worktree's directory and branch slug come from a title derived from your first prompt — ask for "fix the login redirect" and you get `fix-the-login-redirect`. When no usable title can be derived, Continuum falls back to a **city name** from a pool of \~200 globally-recognizable cities, kebab-cased for git (`Cape Town` → `cape-town`). City assignment is unique per session and persists across restarts — `~/Library/Application Support/Clawdmeter/city-assignments.json` on Mac, UserDefaults on iOS — so a session keeps the same city for its whole life. Cities also serve as the compact display label where a full title won't fit: the iPhone sidebar, the Watch complication, and Live Activities. ## Where sessions run A session doesn't have to run on the Mac in front of you. Continuum can place it on a local or remote Mac, a Windows or Linux desktop running the bundled daemon, a VPS, a Tailscale device, a runner in your own AWS or Railway account, or a short-lived serverless lease it wakes on demand and lets sleep when idle. The iPhone, Watch, web app, and Android app are always remotes — they drive a session, they don't host one. Pick the host with the **Device** chip at spawn time. See [Remote devices](/docs/features/remote-devices) for enrolling hosts and how each transport (relay, LAN, Tailscale, SSH tunnel) is chosen. ## Continuing a session Resume is automatic for managed sessions. Continuum persists the CLI's own session id — read out of the transcript header, `sessionId` for Claude and `payload.id` for Codex — and when it needs to respawn (after a config change, a plan approval, or an idle child exiting) it relaunches the runtime with `--resume ` pinned to the same transcript, so history stays continuous. Earlier builds surfaced every recently-touched JSONL as a "Recent" row you could right-click to continue. That discovered-sessions surface was removed when the sidebar became managed-only. There is no "Recent (last 30 days)" list and no "Continue here" context action in the current sidebar. ## Environment variables An agent that can't reach your database URL or API key is an agent that can't run your tests. **Settings → Env Variables** manages the environment each session is spawned with, per repo. It resolves in two layers at every launch: 1. **Your repo's own `.env*` files, read live.** Continuum references them where they sit — it never copies, uploads, or rewrites them into its own store. A repo works the moment you add it, and editing `.env` takes effect on the next launch instead of being shadowed by a stale copy. 2. **Managed variables**, which override the files. Group them into named **sets** per repo — a `dev` set and a `staging` set, say — and switch which set a session gets. Values live in the Keychain, and the active set's block is written into the repo's `.env.local` so every dotenv-aware tool the agent runs (Vite, Node, your test runner) picks it up too. The **Variables** table lists key, sets, type, status, and last-updated. **Import .env** adopts what's already on disk; a scan panel lists unmanaged keys it found, with the file and line each came from, and an **Adopt all** action. **Values are write-only over the wire.** They go up in a request body and never come back down in a response — the row type the API returns has no value field at all, so this is enforced by the shape of the protocol rather than by remembering to redact. Lists show `••••••••`; revealing a value is a Mac-local action. Agents receive the environment they need to run, but the key names are all that ever appear in a transcript. Keys that control process loading, hooks, or endpoint routing — `DYLD_*`, `LD_PRELOAD`, `NODE_OPTIONS`, `GIT_SSH_COMMAND` and their kin — are **refused**, on import and again at the spawn boundary. A repo you cloned can't plant one, and neither can a remote client. An import that dropped such a key tells you which ones it refused. You can manage the same variables from iPhone, Android, and the web app; they call the same endpoints on your host, under the same write-only contract. ## Sub-chats `Cmd+;` branches a sub-chat off the currently open session (it's also **New sub-chat** in the session's context menu). Sub-chats are full sessions with their own transcripts, nested under the parent in the sidebar. Use one to explore an alternative approach without disturbing the main session. A sub-chat shares the parent's checkout, so archiving the parent won't reclaim a worktree a live child is still using. ## Archive and search Archive a session from its context menu. Archived sessions are hidden by default; the status filter's **Archived** view reveals them. You can also archive every session in a repo at once from the project header's context menu. The search field filters across visible session titles. Archiving a worktree session **reclaims its worktree**: the runtime is torn down and the checkout is deleted, with build output removed outright rather than parked in a Trash nobody empties. Before deleting anything, Continuum records the session's branch on the row and cross-checks an on-disk ownership marker against the session record — so unarchiving re-creates the checkout from that branch, and a reclaim can never trash a directory a live session still references. Archive reclaim was supposed to work all along and silently didn't — one machine had accumulated 67 stale worktrees and several gigabytes. 0.73.0 fixed the reclaim path and added a background sweeper that cleans up everything that leaked before, so upgrading reclaims your historical backlog without you doing anything. ## Stable project order Projects keep a **stable order** rather than re-sorting by most-recent activity — creating a new session never makes its repo jump to the top. The default is oldest-first by first use, so a newly-added repo lands at the bottom. Drag a project header's grip to reorder (or use the **Move up / Move down** context-menu fallback); your manual order is layered over the default and persists per machine. ## Artifacts Files the agent writes are collected into an artifacts view — the **Files** tab in iPhone session detail, and on the Mac an **Artifacts** pane you reach by right-clicking the review pane's tab bar. Opening a file previews it in place. The daemon endpoint that serves artifact bytes (`GET /sessions/:id/artifact`) is hardened against path escape: * The requested path is canonicalized (`..` / `~` / `//` collapsed) and required to live under the session's working directory, then re-checked after resolving symlinks — so neither `?path=../../../etc/passwd` nor a symlink planted inside the worktree can read outside it. * The file is opened with `O_RDONLY | O_NOFOLLOW`, walking one path component at a time, and the size cap is enforced on the live file descriptor — closing the validate-then-read race. Symlinks are rejected, and anything that isn't a regular file (directory, fifo, device) is refused. * Files over **50 MB** are refused. ## Sources The **Sources** view lists every file and URL the agent cited via its `Read`, `Grep`, `Glob`, `WebFetch`, and `WebSearch` tool calls, with repeat references counted. Use it to audit what the agent actually consulted. Sources is an **iPhone** surface — it lives in the session detail's overflow tabs alongside PR and Files. It was folded out of the Mac review pane, whose visible tabs are now **To-dos, Plan, Diff, Preview, and Terminal**; a persisted Sources selection folds back to To-dos. ## Spawn mode For launching several interactive agent CLIs at once, the Code sidebar's **Spawn** button opens a grid of plain agent-CLI terminals in the project you have selected. Pick a total tile count and an agent mix; each tile is a live, scrollable terminal you type into directly. Spawn groups are ephemeral — they die with the app and are never paired to iOS. See [Spawn mode](/docs/features/spawn-mode). ## Related * [Plan mode](/docs/features/plan-mode) — the Plan/Code pill and the approve flow. * [Composer](/docs/features/composer) — slash commands, mentions, attachments, and the send flow. * [Diffs and PRs](/docs/features/diffs-and-prs) — reviewing what the agent changed. * [Code](/docs/surfaces/code) — the full workbench layout. * [Remote devices](/docs/features/remote-devices) — running sessions on a second machine, a VPS, or a cloud runner.