Projects and sessions
The sidebar groups sessions under the project they belong to. A project is simply a workspace folder; Orbit keeps its own project list so you can add and remove workspaces without touching pi. Removing a project from the sidebar never deletes the sessions underneath it.
Every session is a file under ~/.pi/agent/sessions/ — the same store the pi CLI uses. A session started in Orbit can be resumed from the terminal and vice versa.
Starting a session
- Press ⌘+N (Ctrl+N) or click New task in the sidebar.
- Pick a workspace. Recent folders are listed, and the browse button opens a native folder picker.
- Choose a model, a thinking level, and an access mode from the composer.
- Type a prompt and press Enter. Orbit spawns a
piprocess for the session and streams the reply.
Workflow modes
Scope a session to how you want the agent to behave. The mode is stored per session and enforced by a bundled pi extension.
| Mode | Behavior |
|---|---|
| Plan | Read-only. Write tools are dropped and bash is gated, so the agent can explore and propose without changing anything. |
| Build | The full toolset. Edits and commands run subject to the access mode. |
| Ask | Read-only, like Plan, but without the planning framing — good for questions and explanations. |
Access modes
The access mode decides which tool calls run without asking. Choose it from the composer's access chip: Supervised asks before every command and file change, Auto-accept edits applies file edits but still asks before commands, and Full access never prompts. When a call needs approval, an inline bar above the composer offers Allow once, Always allow this tool, or Deny.
Access modes has the full decision table, the per-mode allowlist, and why this is a guard rather than a sandbox.
Sending: queue or steer
While the agent is working, Enter either queues a follow-up or steers the running task. Pick the default in Settings → Agent → Behavior; Alt+Enter uses the other mode, and ⌘+⇧+Enter (Ctrl+Shift+Enter) always steers.
- Queue delivers the message after the current turn settles.
- Steer takes effect once the current response and its tools finish — it does not cut a tool call off mid-flight.
- Shift+Enter inserts a newline, and when idle Enter sends normally.
Organizing
- Rename, pin, clone, delete, or copy the id from a session's row menu. Pinned sessions sort first.
- Sort projects by last activity, recently added, name, or session count.
- Sessions are cross-workspace: one project can hold sessions from any folder, and switching workspace switches what the sidebar, Explorer, terminal, Git page, and agent operate on.
Moving between sessions
| Keys | Action |
|---|---|
| ⌘+1 … ⌘+9 | Open the Nth visible session in the sidebar order. |
| Ctrl+Tab / Ctrl+Shift+Tab | Cycle to the next / previous session. |
| ⌘+⇧+B | Move keyboard focus to the sessions list. |
| ⌘+P or ⌘+K | Open the command palette to jump to a session or command. |
On Windows and Linux, replace ⌘ with Ctrl. See Keyboard shortcuts for the complete list.
Live updates and notifications
- Sessions written by the CLI or another Orbit window refresh in the sidebar live. ⌘+R reloads them from disk.
- When a turn settles and the window is not frontmost, Orbit shows a desktop banner and plays the alert sound. If Orbit is frontmost you get an in-app toast instead.
- If a run is waiting on an extension dialog, Orbit raises a heads-up so the prompt is never silently stuck.