Create Your First Space

A space in SpaceSpider is the unit of work: a named directory, a grid layout, and a CLI locked to each pane. Once you create one, reopening it respawns the whole grid with the same CLIs in the same working directory. This page walks you through the wizard step by step and explains the choices behind each step.

What a space actually is

Internally, a space is a record in spaces.json with four pieces of data:

• A unique ID (nanoid).
• A short, human-readable name.
• An absolute directory path that becomes the cwd for every pane.
• A grid definition: the preset (1, 2, 3, 4, 6, 8, or 9 panes) and the CLI assignment for each slot.

Closing and reopening a space spawns fresh PTYs. SpaceSpider does not persist terminal scrollback across sessions; that is intentional, because it keeps each session clean and avoids storing potentially sensitive output on disk.

Before you start

Make sure the following are true:

• You have installed at least one AI CLI. See Install on Windows, macOS, or Linux.
• The CLIs you want to use respond to --version in a regular terminal.
• You have a real project folder in mind. Empty folders work, but you get more out of a space when there is code for the agents to read.

Step 1: Pick a folder and name the space

1. Launch SpaceSpider. The home view shows every space you have already created, plus a large New Space tile.
2. Click New Space. The wizard opens over the home view.
3. On the Folder step, click Choose folder and select your project root via the native folder picker. On Windows this is the standard shell dialog; on macOS and Linux it is the system file chooser.
4. The selected path appears under the button. Confirm it is the right directory.
5. Enter a short name in the Name field. Eight to twenty characters is ideal; the name shows up in space cards on the home view and in the top bar of the grid view.
6. Click Next.

Tips for naming:

• Use the repo or product name, not the full path. "api-server" is better than "work-monorepo".
• If you create multiple spaces pointing at the same directory for different grid shapes, append a suffix like "review" or "bugfix".

Step 2: Choose a grid layout

The Grid step shows a preview of the seven supported presets: 1, 2, 3, 4, 6, 8, and 9 panes. Each preset is a plain CSS grid with equal-sized cells.

Pick based on how many CLIs you plan to run at once and how large your screen is:

• 1 pane: you want SpaceSpider as a focused single-CLI launcher. Same as a regular terminal window but scoped to a directory.
• 2 panes: the default for most workflows. Claude Code on one side, a shell on the other for running tests and inspecting diffs.
• 3 panes: a common three-column setup. Works well on ultrawide displays.
• 4 panes: the sweet spot for agent comparison. One quadrant per AI CLI.
• 6 or 8 panes: for large monitors where you are running many background tasks alongside agents.
• 9 panes: reserved for huge displays and advanced users. Readability suffers below 13-inch screens.

A deeper comparison lives on Grid layouts.

Click a preset to select it, then click Next.

Step 3: Assign a CLI to each pane

The CLIs step lays out a grid with the same shape you picked, but each slot is a drop zone. Click a slot to open the CLI picker; select a CLI tile to bind it to that slot.

The picker shows the supported CLIs:

• Claude Code (the Anthropic CLI).
• Codex (the OpenAI CLI).
• Qwen Code (the Alibaba Qwen CLI).
• Kimi CLI (the Moonshot Kimi CLI).
• Plain shell (cmd/PowerShell on Windows, zsh/bash/fish on macOS and Linux).

Each tile shows a green dot if the command is on your PATH right now. Tiles for CLIs that are not installed still work; you can select them, but the pane will show "command not found" until you install.

Tips for assignment:

• Put the CLI you interact with most in the pane you focus most, which is usually top-left.
• Reserve at least one shell pane per space. You will want it for running tests, git commands, and log tails.
• If two panes are assigned the same CLI, each gets its own independent PTY session. Useful for running the same agent on two branches.

Click Create when you are done. The wizard closes and the grid view opens.

What happens the moment you click Create

Under the hood, SpaceSpider does the following for each pane:

1. Resolve the spawn command for the selected CLI from the built-in catalog (cliCatalog in the frontend, CLI_CATALOG in the Rust backend).
2. Call the pty_spawn Tauri command with the space directory as cwd, the command and args, and the current cell size.
3. Subscribe to pty://output/{id} events and stream them into the xterm.js renderer.
4. Subscribe to pty://exit/{id} for restart and cleanup logic.

You see all of that as: each pane flashes, shows a banner from its CLI, and lands at a prompt ready for input.

Reopen, rename, or delete a space

Back on the home view, each space is a card. Click the card to open it. Right-click (or long-press on touch devices) for a menu:

• Open: same as clicking.
• Rename: edit the name in place.
• Duplicate: clones the space with a new ID and -copy suffix so you can experiment without losing the original.
• Delete: removes the entry from spaces.json. The directory itself is not touched.

Edit a space's grid or CLIs

Right now, editing the grid shape requires recreating the space. You can swap the CLI in any pane on the fly using the picker shortcut (Ctrl+Shift+T or Cmd+Shift+T), and that change is saved to spaces.json automatically.

Troubleshooting first-space creation

• Picker shows the wrong folder: your OS file picker remembers the last location. Navigate up and pick again.
• "Space already exists": you already have a space with the same name pointing at the same directory. Names must be unique per directory.
• Pane opens but immediately exits: the CLI failed to start. Open it once in a normal terminal to see the real error.
• Grid preview is misaligned on HiDPI: zoom to 100 percent; DPI scaling above 150 percent stretches the preview tiles slightly.

More general help is on Troubleshooting.

Frequently asked questions

Can I have multiple spaces pointing at the same directory?

Yes. Each gets its own grid shape and CLI assignment.

Can I use a network drive or UNC path?

On Windows, UNC paths work but are slower to spawn PTYs. On macOS and Linux, SMB mounts under /Volumes or /mnt work without issue.

What if my CLI is in a non-standard location?

Add its directory to your PATH before launching SpaceSpider, or symlink the executable into /usr/local/bin (macOS/Linux) or a directory that is already on %PATH% (Windows).

Does a space remember its scrollback?

No. Each session starts fresh. Use redirection inside the pane (tee or similar) if you need to capture output for later.

How many spaces can I have?

There is no hard limit. The home view uses a virtualized grid, so hundreds of spaces load quickly.

Related reading

• Grid Layouts: 1 to 9 Panes Explained
• Keyboard Shortcuts Reference
• Using Claude Code in SpaceSpider