DeckSpace docsYour first workspace
A workspace is a name and a folder on disk. Everything else — panes, agents, memory — hangs off that folder.
DeckSpace ships no model. It runs the agent CLIs you already have installed, inside terminal panes, rooted at a directory you choose. Getting to real work is three things: finish or skip the first-run wizard, create a workspace pointed at a project folder, and put an agent in a pane.
The first-run wizard
On a genuinely fresh install one overlay appears before anything else. It is gated on a single browser-storage flag, deckspace.onboarded.v1, so it renders exactly once. Every step is skippable, Skip setup is visible on every step, and pressing Escape deliberately does nothing.
| Step | What it does | Skippable |
|---|---|---|
| Welcome | Intro only. | yes |
| API keys | Stores provider keys for DeckSpace’s own features, and offers a one-click Detect installed AI CLIs scan. | yes |
| Voice | Voice provider, voice and assistant name. | yes |
| Your Mac | An opt-in scan of how your home folder is organised, saved to the local memory vault. It does nothing unless you click the scan button. | yes |
| Permissions | macOS permission grants for dictation and the voice assistant. | yes |
| Autonomy | Picks one of three presets and writes it into the same setting Settings → Autonomy uses. | yes |
The Autonomy step offers three labelled choices, and they map onto the app-wide presets described in What walk-away does:
| Wizard choice | Preset it writes |
|---|---|
| Balanced | plan |
| Ask every time | ask |
| Full autonomy | walkaway |
The source comment beside the Full-autonomy option says agents “stay write-confined to their own folder.” The kernel write fence only wraps panes where the agent CLI is the pane’s process. The panes this wizard creates are shells with a command typed into them, which is a different path — see Opening the first pane below, and What walk-away does for which panes are fenced and which are not.
The first-run wizard does not create a workspace. When you finish or skip it and no workspace exists yet, it hands off to the workspace wizard described next. You can run the first-run wizard again later from Settings.
Creating the workspace
The workspace wizard has four steps. It also opens from the + button in the left rail (tooltip: New workspace) and from the New workspace button on the empty stage.
| Step | What you set |
|---|---|
| 1 · Start | Workspace name, and a type: Standard (terminal grid), Swarm (opens into the swarm room), Canvas (opens into the browser view). The type only chooses which view the workspace opens into — everything stays reachable from the dock. Saved presets, if you have any, appear here. |
| 2 · Layout | The working folder, and how many terminals. |
| 3 · Agents | Optionally pick one detected agent CLI and a first prompt. |
| 4 · Permissions | The same macOS voice and assistant grants as the first-run wizard. Optional. |
On the Layout step you can click the folder button to open the native directory picker, or type or paste a path into the text field below it. The text field is always present, deliberately, because it still works when the native picker fails to open. Recently used folders appear as buttons.
The terminal-count buttons offer 1, 2, 4, 6, 8, 10 and 12, and the grid is derived from the count:
| Terminals | Grid |
|---|---|
| 1 | 1 × 1 |
| 2 | 2 × 1 |
| 4 | 2 × 2 |
| 6 | 3 × 2 |
| 8 | 4 × 2 |
| 10 | 5 × 2 |
| 12 | 4 × 3 |
The hard ceiling elsewhere in the app is 16 panes. The wizard does not offer every value up to that.
Before adding the workspace, DeckSpace asks the backend to point at the path. That call rejects anything that is not a directory, and the workspace is not created — you get a warning toast naming the path instead of a workspace that renders in the rail but sends every command to the previous folder. A pasted path with a typo hits this.
Pick a project directory, not your home folder
The folder you choose is where every pane’s shell starts, where the file tree and git panel read, and where agents work. Two limits are worth knowing before you pick.
Leaving the folder blank is allowed. The wizard lets you finish with no folder at all, and that workspace is a bare terminal grid. Nothing points the backend anywhere, so the panes open in whatever directory the backend already held — on a fresh install, that is your home directory. If you did not mean to do that, set a folder.
Some roots are refused for code indexing. A workspace rooted at your home directory, at /, at a volume root, at ~/Library, or under /System, /usr, /bin, /sbin, /Applications, /Library, /private or /Volumes is excluded from the index walk. The workspace still opens and the panes still work; the features built on the index do not get one.
The file tree also never expands a fixed list of heavy directories, whatever root you choose — among them node_modules, .git, target, dist, build, .next, .venv, __pycache__, coverage, vendor, Pods and DerivedData.
What DeckSpace finds on your PATH
Detection is a PATH lookup, nothing more. DeckSpace checks each known command name against a PATH it assembles itself, and reports the ones it can resolve to a file. It does not run them, install them, or read your API keys.
| Agent | Command it looks for |
|---|---|
| Claude Code | claude |
| Codex | codex |
| Aider | aider |
| Antigravity | agy |
| Gemini (legacy CLI) | gemini — retired 2026-06-18; new launches redirect to agy |
| OpenCode | opencode |
| Cursor Agent | cursor-agent |
| Droid | droid |
| Copilot CLI | copilot |
| Grok CLI | grok |
| Amp | amp |
| Qwen Code | qwen |
Anything you have registered yourself is probed the same way and listed after the built-ins.
How that PATH is built
A GUI app launched from Finder or the Dock inherits a minimal PATH that has none of the version-manager shims your terminal has. DeckSpace works around that once per run, in this order:
- The PATH this process was started with.
- The PATH your login shell prints, obtained by running your
$SHELLas-licand reading$PATH. This step is capped at 1.5 seconds and the child is killed if it overruns. - A fixed list of per-user directories under your home:
.local/bin,.grok/bin,.opencode/bin,.cargo/bin,.bun/bin,.npm-global/bin,.deno/bin,.volta/bin,.local/share/mise/shimsandbin. /opt/homebrew/bin,/usr/local/bin,/usr/bin,/bin.
The result is cached for the life of the app, and every pane and headless run uses it.
Step 2 is the one that finds nvm, asdf and mise shims. If your login shell takes longer than 1.5 seconds to start — a heavy .zshrc, a prompt framework, a network call in a shell hook — the probe is killed with no error, no toast and no log line in the UI. Detection then falls back to steps 1, 3 and 4 only, and an agent CLI that a terminal finds instantly is reported as not installed. The Agents step says “No agent CLIs found on PATH” and the wizard continues normally.
If you know a CLI is installed and DeckSpace disagrees, check whether it lives in one of the directories in steps 3 and 4. If it does not, either move or symlink it into one, or register it in Settings by its absolute path — an absolute path is checked directly and skips PATH resolution entirely.
The same login-shell probe is what supplies environment variables your GUI process never saw — an ANTHROPIC_API_KEY exported from ~/.zshenv, for example. It carries the same 1.5-second cap and the same silence when it expires, and only variables this process does not already set are added.
The login-shell PATH query and the login-shell environment query are both guarded #[cfg(not(windows))]. On a Windows build neither runs at all: PATH is the process PATH plus the fixed directory lists, and no shell-exported variable is ever picked up. Windows also adds .exe, .cmd and .bat when resolving a command name.
The first-run wizard’s Detect installed AI CLIs button does slightly more than the workspace wizard: it also runs each resolved binary with --version, capped at 3 seconds per CLI, on one thread per CLI. That version string is only ever shown to you. The scan runs on your click and never at startup, and its result is cached locally so a return visit renders instantly.
Opening the first pane
The workspace wizard ends with two buttons.
| Button | What happens |
|---|---|
| Open empty workspace | The grid opens with a shell in each pane, rooted at your folder. You type whatever you want. |
| Open with <agent> in every pane | Only appears once you have selected an agent on step 3. Waits for each pane’s terminal to come up, then types that agent’s launch command into it. |
For the second button, each pane receives an export OPX_GUARD=1 line first, then the agent command. That guard is the destructive-command seatbelt — it is a seatbelt, not a boundary. Panes you open and type into yourself never get it.
The fence wraps a pane only when the agent CLI is spawned as the pane’s own process. This wizard launches by typing a command into an already-running shell, which is the other path. The autonomy preset you picked in the first-run wizard still applies; the fence does not. What walk-away does has the full table of which panes are fenced, and which platforms have a fence at all.
The first prompt, and what happens to it
If you typed a first prompt and asked for more than one terminal, DeckSpace does not send the same text to all of them. It first runs your selected CLI once, headlessly, asking it to split your goal into exactly N parallel subtasks, then sends one subtask per pane.
The split is a single headless invocation of the form <bin> -p <prompt>. That -p flag is hardcoded for every agent, so a CLI that does not accept -p as its prompt flag exits non-zero. Any failure — wrong flag, missing auth, non-zero exit — is caught and falls back to filling all N panes with your original text. There is no error, no toast and no visible difference: you get N agents doing the same job.
The same fallback fires quietly when the CLI returns fewer lines than you have panes. If you want distinct work per pane, write the per-pane instructions yourself rather than relying on the split.
That split call also runs without the write fence: the wizard does not ask for it, and the default when it is not asked for is off. It is a short read-and-plan call, but it is a real agent run in your workspace root.
Panes whose terminal does not register within 8 seconds are skipped — the pane is there and usable, it just does not receive the launch.
What gets written into your folder
Adding a workspace with a folder triggers two writes into that folder. Both are idempotent and neither clobbers your files.
| Path | What lands there |
|---|---|
.opxmemory/workspace.md | A pinned workspace note with the path and creation date, and two empty sections for you to fill. Written only if absent. |
.opxmemory/daily-<date>.md | Today’s log note. Written only if absent. |
.mcp.json | Three MCP server entries — opxmemory, opxmemory_global, opxboard — so agent CLIs launched here can reach memory and the board. |
If .mcp.json already exists, DeckSpace merges in only the keys that are missing and leaves everything else alone. If the existing file does not parse as JSON, or its top level is not an object, or mcpServers is not an object, it is left completely untouched and no servers are added.
Adding a workspace must never fail because seeding failed, so errors from either write go to the developer console and nowhere else. If .opxmemory/ or the MCP entries are missing after creating a workspace, nothing on screen will have told you. Check the folder.
Note that .opxmemory/ is live product data read by the app’s Memory room, not scratch space. See Memory.
More than one workspace
Workspaces are listed in the left rail, each with its own name and colour, and the list is persisted so it survives a restart. Switching one repoints the backend at that folder.
Switching to a workspace whose folder is no longer there switches the view immediately, then tells you that agents are still running in the previous workspace until you repoint it. Closing a workspace kills its shells and agents first, so nothing is orphaned.