Sessions

A session is an agent conversation — a running claude or codex — bundled with a workspace to work in and a saved configuration. It's the unit you spawn, talk to, and tear down.

The main session

The session you land in when you run actor claude is the main session — shown as main, marked with a crown in the menu. It carries a system prompt that makes it a coordinator for the rest of your sessions: it spawns them, hands them bounded tasks, records what each is responsible for, and verifies their work before treating it as done. You describe outcomes; it handles the delegation.

It manages by exception. With many sessions active, you don't want a ping on every event, so main stays quiet through routine progress and surfaces only what needs you: a decision, a blocker, a risk, or a finished objective ready for review. It's not a gatekeeper, though — every session is an agent you can attach to and instruct directly, and every lifecycle operation is a plain CLI command.

The completion channel

Sessions run in the background, so main needs to learn when they've done something. It doesn't poll. Each time a session finishes a turn, a completion arrives at main over a notification channel, carrying the session's name and its last message. Stops and unexpected exits arrive the same way; clean, intentional endings stay silent. main reacts by relevance: a completion from a session it is coordinating for you is signal — it verifies, integrates, and continues the plan — while events from a session that isn't part of any active task are left alone.

Even when you switch into another session's terminal from the session menu, main keeps running in the background. That's why quitting another session drops you back to main rather than ending everything — the session you launched is the root, and it persists until you quit it directly.

Isolated worktrees

By default, every session runs in its own git worktree at ~/.actor/worktrees/<name>/, on its own branch. A worktree is a second working copy of the same repository: the session sees the full history but edits a separate checkout, so its changes never touch your working tree or another session's. Several sessions can work on the same repository at once without conflicts.

You can opt out with --no-worktree, which runs the session directly in an existing directory. Use it when isolation isn't worth a separate checkout — but the session then shares that directory's state, and discarding it won't clean anything up.

Lifecycle

Every session moves through the same four operations, available from both the CLI and the MCP tools main uses:

Discarding is safe by default

discard removes the worktree but never deletes the branch — commits stay reachable on it. The default on-discard hook also refuses to discard a session whose worktree has uncommitted changes (staged, unstaged, or untracked). Commit or push first, or pass --force to override. See Hooks for how the check is wired.

Where things live