Start your first workspace
A workspace is one CLI agent process attached to one folder on one host. You can have many workspaces alive at once, each in its own tmux session.
The "New workspace" modal
Click + New in the sidebar (or hit ⌘K / Ctrl+K). The modal has three entry tiles:
| Tile | When to use it |
|---|---|
| 📁 Open project | Point at an existing folder on the host. The most common path. Works on any folder — git or not. |
| 🌐 Clone from Git | Have the agent git clone a remote repo into a new folder, then spawn. Requires Pro+. PATs entered here are ephemeral — never persisted. |
| ✨ New project | mkdir a fresh empty folder under a parent of your choice, then spawn. Useful for greenfield work. |
After you pick the tile, the modal asks for:
- CLI agent — claude-code, codex, cursor, gemini, opencode, or the bundled "stub" (a noop, good for sanity-testing the dashboard plumbing).
- Branch — only shown for git folders. Defaults to
main. - Isolation — also git-only. Direct (the default on every tier) runs the CLI in your project folder, in place. Worktree (Pro+) gives the workspace its own checkout so parallel branches don't trample each other. See direct vs worktree.
- Name — optional human label; defaults to
<branch>@<repo>. - 🔔 Notify me when the agent needs attention — see push notifications. Pro+ feature.
What happens on spawn
- Qorin tells the agent to create a tmux session, e.g.
ws-12ab34cd-claude-feat-x. - If you picked Worktree isolation, the agent creates a worktree for the chosen branch (so the original checkout stays clean). In Direct mode it just checks the branch out where it is.
- It runs
<cli-agent>(e.g.claude) under your OS user via the login shell, with your$HOME, dotfiles, and CLI auth. - The PTY is exposed over the WebSocket; your browser attaches and renders the terminal.
Status pills:
- spawning — the agent is mid-startup
- running — actively executing
- idle — process is alive but no output for a while
- awaiting_input — the CLI is asking for permission (e.g. "may I run rm -rf?") or its turn ended and it's your move. With notifications on, this is what opens the workspace's attention request — one per workspace, closed again the moment you open it, the CLI resumes, or the process ends. See notifications.
- completed / failed / discarded — terminal states
Common workflows
Two branches at once: spawn the same repo twice with different branches. Pick Worktree isolation (Pro+) for both and the file edits don't fight.
Different CLIs, same task: spawn one workspace with claude, one with codex, one with opencode, on the same branch — each in its own worktree. Compare.
Hand the CLI a file: 📎 in the terminal toolbar, either from this device or from the host. Pro+ for the upload half — see attach a file.
Quick scratchpad: ✨ New project → name it scratch → spawn with stub (or any CLI). Throwaway.
Switch and split
Click a workspace in the sidebar to switch the main pane to its terminal. Click the 📌 pin icon to also pin it as a secondary view — Qorin splits the main pane 50/50 so you can watch two workspaces side-by-side.
We keep previously-opened workspaces mounted (just hidden) so flipping back is instant — no reconnect, no scrollback loss.
Next reading
- Workspaces guide — lifecycle, modes, cleanup
- Repositories — the 3-tile model in detail
- Notifications — hook into the CLI's permission prompts