Skip to main content
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: The Device menu lists This Mac, Continuum Cloud (when your account is entitled to hosted inference), and every execution host 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 ride the same OpenCode connector as OpenCode Go but keep their own credentials, catalog, and spend column. Continuum is the hosted 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. 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 — 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/<project>/<slug>, 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 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 <id> 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 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.
  • Plan mode — the Plan/Code pill and the approve flow.
  • Composer — slash commands, mentions, attachments, and the send flow.
  • Diffs and PRs — reviewing what the agent changed.
  • Code — the full workbench layout.
  • Remote devices — running sessions on a second machine, a VPS, or a cloud runner.