Docs

Getting started

SpaceVibe Deck is a desktop terminal for running several AI agent CLIs side by side. Each agent runs in its own terminal pane; Deck shows which one is working, which one is asking for you, and what each one just said, and brings you back to the pane that needs you.

Install

Download the current release from github.com/mxrsv/spacevibe-deck/releases/latest.

• macOS, Apple Silicon (arm64). The .dmg is signed and notarized. Intel Macs are not served.
• Windows, x64. The -setup.exe installer is unsigned, so SmartScreen warns on first install. It installs per user, without elevation. Windows ARM is not served, and the Windows build has not been verified on real hardware.

Deck checks for updates on its own, tells you when one is ready, and lets you choose when to download, install and relaunch. See Settings → About.

If you ran the older Tauri-based Deck: its update check fails, and the last published Tauri release does not contain the migration notice. Download and install the current Electron release by hand using the link above. Settings and workspaces do not migrate; it is a clean install. Your Tauri data remains in ~/Library/Application Support/dev.spacevibe.deck on macOS or %APPDATA%\dev.spacevibe.deck on Windows. Electron uses a separate SpaceVibe Deck data folder; see where Deck keeps its data.

First launch

Deck opens on the Open board, the start surface. Beside the folder bar sit three buttons for the most common ways to start: Open folder…, Clone repository… and Create worktree…. The folder bar's menu holds Create workspace…, Resume a session… and Manage agents above your recent folders. The board offers:

• Open workspace… — pick a folder. A workspace is a local folder that becomes the working root for a tab.
• Recent workspaces — selecting a folder fills the workspace and agent choices. Review the selected agent, then choose Open agent to launch it, or double-click the folder to open it at once with its remembered agent (a terminal when no agent can run). A folder that has disappeared from disk cannot be opened.
• Drop files or folders onto Deck or the Open board to save them as workspaces. A file adds its containing folder, and the first folder is selected. Nothing starts until you open an agent; dropping onto a terminal pane still types the path.
• Clone repository… — paste a GitHub repository (owner/repo, an HTTPS or SSH URL), choose where it goes, and Deck clones it with your own Git credentials and adds it as a workspace. Progress shows in the form and you can cancel; closing the form does not stop the clone. It needs Git installed, clones the default branch with its full history, and leaves submodules and dependencies alone. The same entry is on the File menu. Starting an agent in the new workspace stays a separate step.
• Create worktree… — for a git repository, create a new git worktree on a new branch and open it. Worktree and branch are one choice: Deck never offers a branch without its worktree.
• Resume a previous session… — the session history, listing Claude Code and Codex conversations Deck found in those tools' own local logs; a row opens a tab in that session's directory and types the CLI's exact resume command.

When Deck quit with tabs open, the board shows Last session at the top. Reopen brings back those tabs and resumes each agent conversation it can resolve; dismiss it, or open anything else, and Deck starts clean. Scrollback, unsaved file edits and window placement are not restored.

Launch an agent

Press ⌘T (Windows: Ctrl+Shift+T) for the active checkout, or Agent above the Agent Rail (to start one in a checkout that has nothing open, press its name). If you are working in that checkout, the new agent opens beside your current pane; otherwise it opens in a new space there, and the launcher says which before you press Run. Right-click a checkout for the menu, which lists your quick agents; choose one to launch it in that checkout using the command shown in Settings → Agents. Open shell opens a plain shell in a new tab, and New split here opens one beside the current tab. The ⌘T menu also offers Open another project… to choose another workspace (checkout actions).

The window

• Agent Rail (left column). One cluster per project, one row per agent pane. The row shows what the agent last said, or its name if it has said nothing yet. A dot on the agent's logo marks state: red for failed, yellow for asking you, grey once a run is done; a working agent shows a small spinning dot pattern instead. Only the agents that need you keep their logo in full colour, so those rows stand out as you scan the column. Clicking a row focuses that pane. Each row's ✕ closes the thing it names: an agent row closes that pane, a project header closes every tab of that repository. Drag a project header to reorder clusters.
• Stage (centre). The terminal panes of the active tab, split as you like. Above them, one strip of chips: terminal tabs, open documents and the browser tab share one shape and are ordered by when they were opened.
• Side panel (right, ⌘⇧J). Three tabs: File explorer (⌘⇧B), Token usage (⌘⇧U) and Session history (⌘⇧Y).
• Browser tab (⌘⇧I). A page beside your terminals, opening on the home address from Settings → Browser.
• Dev servers (macOS, at the end of the tab strip). A chip counts the servers running in the project you are on; press it for the list. It finds servers started from Deck or from any other terminal or editor. Each one can be opened in Deck or in your browser, or copied. The chip does not appear where Deck cannot look for servers.

Drag the seam between the rail and the stage to resize it. Drag it past its floor, press ⌘B or use the toggle beside the traffic lights to collapse the rail to a column of project avatars. A badge on an avatar counts the agents waiting on you, and pressing one opens that project's sessions beside the column. ⌘B or the toggle at the start of the tab strip expands it again.

Panes and tabs

• Split with ⌘D (side by side) or ⌘⇧D (stacked). Move between panes with ⌘⌥ arrows; swap two panes with ⌘⌥⇧ arrows.
• A plain shell pane in a split tab has a header with your pinned agents' logos. Press one to run that agent in the pane's shell. The header also holds the split, expand and close buttons.
• ⌘E expands the focused pane; ⌘⇧Enter zooms it over the whole tab.
• ⌘W closes the focused pane; ⌘⇧W closes the whole tab. Deck asks first if a process other than an idle shell is running there.
• ⌘⇧T reopens the last closed tab with fresh shells at the same directories.
• ⌘⇧M moves the focused pane into its own window.
• ⌘1–⌘8 select a chip by position; ⌘9 the last one; ⌘⇧] / ⌘⇧[ cycle.
• ⌘⇧A jumps to the pane that most needs you.

Files

Open the file explorer (⌘⇧B) to browse the workspace. Opening a file splits the sidebar: the list stays against the right edge and the document appears to its left, while the terminal remains visible. Use Open files to return to a retained document; unsaved files carry a dot. With the document focused, ⌘S (Windows: Ctrl+S) saves and ⌘W closes it. Markdown opens rendered; ⌘⇧V flips it to source. See the file panel.

The eye button on the folder's row shows or hides dot-files such as .env and .github. The tree also hides what the repository's .gitignore rules ignore, such as node_modules or build output, and the funnel button next to the eye shows those entries dimmed. Outside a git repository node_modules, dist and target count as ignored. .git is always hidden. The row of the document beside the list is highlighted, and switching documents opens the folders above it and scrolls it into view.

In a git checkout, switch the explorer from Files to Changes to see what has changed since the last commit: each file with its status and added and removed lines. Click one to open it.

If tracked files require executable Git filters, such as Git LFS, Changes reports that it cannot read them safely; use your usual Git client for those files. Submodule commit changes are shown, but file changes inside a submodule are not scanned. See the Changes reader.

Markdown diagrams do not load external HTTP(S) images in the installed app. The image policy does not affect the browser panel.

⌘+click (Windows: Ctrl+click) on a path an agent prints opens it. A path inside a workspace this window has open lands in Deck's own editor at that line; anything else goes to the app chosen in Settings → Links & editor. On Windows only the in-Deck half works in this release.

Usage and privacy

The Token usage tab reads Claude Code's and Codex's own local session logs and groups tokens and estimated cost by agent and day. It needs no account.

Starting with 1.1.0, Deck sends cumulative usage snapshots for each day. Analytics are always on, with no opt-out, beginning on the first launch after upgrading; 1.0.0 and the older Tauri releases send no analytics. Each snapshot contains a fresh random id for that day, Deck's version, platform and architecture, launch counts per built-in agent, how often the browser, explorer and usage surfaces were opened, the day's highest tab and pane counts, and whether sessions were restored. It never contains code, paths, prompts, file names, repository names or a permanent identifier. Settings → Privacy states exactly what is sent and has no switch. The full field list is src/telemetry/payload.ts.

Agents

An agent is a command-line AI tool that Deck runs inside a terminal pane. Deck does not replace the tool's own workflow: it starts the command in a real shell, watches the pane, and reads the tool's own session logs where it knows their format.

Built-in agents

Deck recognises twelve agents out of the box. Each ships with a launch command, and the command is shown on screen in Settings → Agents rather than hidden behind a label.

Codex's -c tui.animations=false turns off its idle animations. Codex keeps repainting its prompt while it waits, and Deck would read that as an agent still working, so the row would show the working spinner before you have typed anything and after the reply has landed. If you write your own Codex command, keep that flag, or set animations = false under [tui] in ~/.codex/config.toml to turn the animations off in every terminal.

Several of these skip the tool's own confirmation prompts. That is the point of Deck, which exists to run agents that keep working, and it is also why every command is spelled out and why each one can be disabled. OpenCode ships bare because its --auto mode is opt-in per session. The seven agents added after Gemini CLI ship bare too: Deck has not read their flag lists, so it offers no flag, model or effort controls for them (Droid's autonomy level and spec mode are the exception) and relaunches them bare on resume.

Until you choose quick agents, quick launch and the checkout menu offer the installed agents: these in this order, then your custom agents (quick agent defaults).

Settings → Agents

The catalog splits on what Deck found on your login shell's PATH:

• Installed — agents whose binary was found. Refresh looks again straight away, including your custom agents.
• Available to install — the rest.

Each agent is one row showing its name and the command it launches with:

• on / off. Turning an agent off removes it from launch choices; a built-in cannot be deleted because the next probe would find it again (agent choices).
• Configure (the arrow) opens the agent's settings under the row:
  • Command — the full launch command appears first. Edit it directly or change the controls under Launch; both edit the same command. Blur or Enter saves a valid edit; invalid text stays in the field with an error. The reset arrow beside a custom command removes that preset and falls back to the next saved command or Deck's built-in command (command editor).
  • Launch — the switches and choices each CLI offers. Two or three choices appear side by side, including CLI default; longer lists use a menu (agent choices).
  • Model — Default model, Default effort and Additional models appear on installed agents whose CLI takes those flags (model settings).
  • Integrations → Signals — on Claude Code, Codex and opencode: use the status the agent reports instead of Deck's estimate, for new sessions. It is on by default for all three. For Claude Code and Codex, Signals installs Deck hooks in their settings; opencode loads a small Deck plugin instead and nothing is written to its config. It also covers commands you type manually inside Deck. For Codex, Deck starts its terminal sessions without Codex's shared background service so the reports reach the right pane, which means those sessions do not appear in codex agents. For opencode, a OPENCODE_CONFIG_DIR you set yourself is not used inside Deck terminals. Turning it off removes this installation's hooks. Reopen terminals created before this integration was installed. Signal integration.
• For an agent under Available to install, choose Configure launch to prepare its command before installation. Model controls appear after Deck detects the CLI (agent settings).
• Add command. Save another command line for an agent. The first one saved for an agent also becomes its command; later ones stand behind it for the reset arrow above. The agent is derived from the command's first word.

A command you write is typed verbatim into a live interactive shell, so it may use only letters, digits, spaces and . , : @ + = _ - /. Pipes, &&, ;, quotes, redirects, variables and newlines are refused with a message saying why. A pipeline belongs in a wrapper script declared as a custom agent. The install commands Deck ships are the vendors' own and are exempt from this rule.

Installing a missing agent

A built-in agent that Deck did not find shows Install on its row in Settings → Quick agents and as a dimmed tile on the launcher, after the agents you can run. Hover it to see the exact command. It opens a terminal named Install <Agent> in a new space (in your home folder when no folder is open), types the vendor's install command and runs it there, so you see every prompt and answer them in that terminal. Pressing Install again while that terminal is open takes you back to it.

Deck does not watch the installer finish. It looks again when you return to the Deck window or open an agent list, or when you press Refresh, and the row then moves to Installed without a restart. An agent installed this way is also added to your quick agents. A terminal that was already open keeps the PATH it started with, so start a newly installed agent from a new terminal. An agent whose install command Deck has not verified shows Get instead, which opens its website. Install and Get appear only for enabled built-in agents, never for custom ones, and only in the Electron app (install control).

Quick agents

Quick agents are the tiles on the quick launcher and the rows in the checkout menu. Choose them in Settings → Agents → Quick agents; the launcher has no list of its own to edit. Your choices are saved; agents you disable or uninstall stop appearing in the menu without being replaced by another agent (quick agent settings).

Hover or focus a tile to see the exact command it will type, the folder and where it lands. The Default profile chip under the tiles lets you pick another of an agent's launch commands for that visit; leaving the launcher forgets the pick, and Edit profiles in Settings… opens where commands are written. If an agent cannot be started, the launcher says why and offers Retry (launcher).

The checkout menu's Open shell opens a new terminal tab inside Deck at that checkout. Use New split here for a pane beside the existing tab (checkout actions).

Custom agents

Under Declared, add any CLI with a name and the command to type into each pane. Click the name or the command to edit either; ✕ removes it. A declared agent stays listed when its binary is missing from PATH so that an uninstalled tool reads as missing rather than as lost data.

Custom agents show a name and a state in the rail but no "latest words": Deck reads session logs only for the built-ins it knows.

What Deck knows about each agent

Working, needs-you and failed states come from the terminal itself (bell, notification and progress sequences the tool emits, plus sustained output) and work for any agent. When Deck reads a needs-you or done state from output timing rather than from the agent, the row's tooltip says (inferred). With Signals on, which is the default, the state is the agent's own report for new sessions, and a needs-you state can say what it waits on, such as a permission prompt. An agent whose process has left its pane reads as ended (rail states).

Token usage

The Token usage tab (⌘⇧U) reads the local session logs of Claude Code and Codex, including Claude Code's sub-agent logs, and groups tokens and estimated cost by agent and day. Ranges are local calendar days: Today, 7 days, 30 days, All. Costs use a pricing snapshot that ships with Deck.

Details at the top of the tab opens a larger Usage page over the main area, with the rail still in view (⌘⇧R, or View → Usage Details). Back or Escape returns you to where you were; choosing a tab or an agent in the rail closes it and goes there.

Keyboard shortcuts

Every shortcut is an action with a name, and Settings → Shortcuts lets you record a different key for any of them. The tables below are the shipped defaults, taken from src/terminal/default-keymaps.ts.

On macOS, bare ⌘C and ⌘V are the system Copy and Paste. On Windows, bare Ctrl+ chords stay available to the shell and the agent, with two exceptions: Ctrl+V pastes, and Ctrl+C copies while the terminal holds a selection and otherwise interrupts the running program as usual.

Launch and navigate

Each terminal tab is a space, shown in the strip as a mark after the current project, branch, space and session. The strip shows the current project's spaces; reach another project from the Agent Rail. The numbers count those spaces first, then open documents and the browser tab. A sideways two-finger swipe over the terminals also moves one space.

⌘⇧O opens Mission Control. Hover a space at the top to see its panes, click a pane to go straight to it, or press Esc to go back unchanged. Nothing stops or restarts while it is open.

Panes

Terminal

Surfaces

Layout presets

A preset is a named split layout with optional per-pane directories. A preset can be created and overwritten, but not renamed or deleted from inside the app.

Notes

• A shortcut that cannot do anything where you are does not eat the key. For example a pane chord pressed over an open document reaches the document instead.
• On macOS, menu-bound chords such as Find and Clear Buffer are consumed by the menu bar before a document can see them.
• Bracket and digit chords bind to the physical key position, so they work on non-US layouts.
• On Windows, Ctrl+S saves the open document, but only while its panel has keyboard focus (routing). Over a terminal it still goes to the terminal, as it always has.
• ⌘⇧V has no Windows binding because Ctrl+Shift+V is paste. Use the toggle on the document surface instead.

Settings

Open Settings with ⌘, (Windows: Ctrl+,). It covers the whole window; leave with Back or Escape. Settings are stored per machine in Deck's data folder as settings.json and apply to every Deck window.

Appearance

Appearance groups color mode, terminal text, workspace chrome and identity. Its read-only preview updates as you choose settings; it does not launch a terminal session.

• Theme — Light or Dark. Dark is the default. On Dark, the terminal is the deepest surface in the window and the chrome stands above it.
• Font and size — shared by terminals and the built-in editor (default size 13).
• Tab bar position — the chips live in the sidebar layout (default) or along the top.
• Show pane bar — a name bar inside each split (off by default).
• Show status bar — branch, path and window readout along the bottom (off by default).

Browser

• Home address — the page the browser tab opens on when there is no previous page to restore (default http://localhost:3000).

Terminal

• Scrollback — lines kept per pane: 1,000 / 5,000 / 10,000 (default) / 50,000 / 100,000.

Agents

The agent catalog: installed and available built-ins, per-agent launch commands, the enable switch, quick-launch choices, and declared custom agents. See Agents.

Links & editor

• Open with — the app that opens a path when you ⌘+click one that no open workspace holds. The list is what Deck found installed among VS Code, Cursor, Zed, GitHub Desktop, GitKraken, Finder, Terminal, iTerm2, Ghostty and Hyper. Paths inside an open workspace always open in Deck's own editor. Detection looks for macOS application bundles, so on Windows no external app is offered in this release.

Shortcuts

Every action with its current key. Click a row to record a new chord; a conflict with another action is called out on the row, and the reset control returns the shipped default. Recording a chord temporarily suspends the menu accelerators so the key reaches the recorder.

Notifications

• Agent notifications — on by default. A window in the background alerts when an agent finishes, asks for input or approval, or fails. Click the alert to return to that pane. If the pane has closed or moved to another window, the alert opens its original window. An older off setting is enabled once by this update; turning it off afterward is remembered. See agent alerts.
• Open System Settings opens the notifications settings on macOS or Windows, where the OS controls delivery. On macOS, allow notifications when the first alert prompts, and use the system's Badges switch to control the Dock count. See notification settings.
• Dock badge (macOS) — the total N need you count across open windows, including finished panes you have not looked at yet. It clears at zero and stays independent of Deck's alert toggle. Windows has alerts but no Dock badge. See attention count.

About

Deck's version, Check for updates, and Release notes. An update is never downloaded or installed without your choice; Deck asks before closing panes to install. That confirmation includes busy work and unsaved files in every open window, as checked by the update census.

Privacy

From release 1.1.0, usage analytics are always on, with no opt-out. This page states exactly what is sent and links to the privacy notice; it has no switch. Snapshots contain daily usage counts, never code, paths, prompts or agent output. Release 1.0.0 and the older Tauri releases send no analytics. See the payload contract.

Analytics state and pending daily counters live in telemetry.json in Deck's data folder, separate from settings.json. A stored off choice from a development build becomes enabled on launch. If telemetry.json cannot be read, Deck counts for that run in memory and leaves the file untouched; the day's counts are lost when you quit.

Search and changed marks

The field at the top of the Settings list finds a setting by the name printed on its row. Each page shows how many matches it holds, and matching rows are highlighted. Esc clears the search before it closes Settings.

A dot after a setting's name means it differs from its default. The dot marks exactly what a page's reset page action would restore: preferences. Declared agents, launch configurations and layout have their own rows under Reset, so they carry no dot.

Reset

The Reset page has three rows: preferences, layout, and custom agents with launch configurations and prompt templates. Each asks first and lists the settings it will change and what it keeps. A row is disabled while nothing in its group differs from the defaults. Pages that hold preferences also show how many differ and a reset page action that touches only that page. Resetting agents and templates also unpins the deleted agents from quick launch. Your custom logo, workspaces and agents’ own session logs stay.

Where Deck keeps its data

On macOS the folder is ~/Library/Application Support/SpaceVibe Deck; on Windows it is %APPDATA%\SpaceVibe Deck.