Workspaces and projects

§ WORKSPACES

The Octopush mental model is two levels deep. A Project is roughly a repository. A Workspace is a git worktree inside that project — an isolated branch checkout with an AI assigned to it. Workspaces are parallel and disposable: spin one up for a task, work in it across all four modes, and tear it down when you’re done.

How to open it

Projects and workspaces live in the left Rail. Select a project to see its workspaces; select a workspace to enter its modes.

[screenshot: the Rail with projects and their workspaces]

Organizing your work

Each project and workspace can be shaped to your liking:

• Rename — give it a clear name.
• Tint and glyph — assign a color tint and a glyph so it’s recognizable at a glance in the Rail.
• Pin and reorder — pin the ones you use most and drag to reorder.
• Archive — keep the branch but drop the worktree. The work is preserved in git; the checkout is removed to reclaim space.
• Delete — remove it entirely.
• Recently closed — restore a workspace you closed by mistake.

Per-workspace configuration

A workspace carries its own setup:

• Setup script — a command Octopush runs to prepare the worktree (install dependencies, generate files, and so on).
• Base branch — the branch this workspace’s worktree is cut from.
• Test command — the custom command REVIEW runs for this workspace.

Jira auto-linking

If a workspace’s branch name contains a Jira issue key, Octopush auto-links the ticket. The active-ticket chip then appears with the issue’s status, ready for you to navigate. See Issue tracking for the full integration.

A typical flow

1. Open a project in the Rail.
2. Create a workspace, choosing its base branch.
3. Give it a tint and glyph, and a name that matches the task.
4. Set a setup script and a test command for the workspace.
5. Work across TALK, RUN, REVIEW, and DIRECT.
6. When the task ships, archive the workspace to keep the branch but free the worktree.

Shortcuts

Shortcut	Action
⌘K	Command palette — jump to sessions, switch theme
⌘⇧1–⌘⇧3, ⌘⇧D	Switch modes within the active workspace

Tips

Archive instead of delete

Archiving keeps the branch in git and only removes the worktree checkout. It’s the safe way to clean up the Rail without losing work — you can always cut a fresh worktree from the branch later.

Note

Because every workspace is a separate worktree, two workspaces never share a working tree. You can have an agent rewriting files in one workspace while you read a clean checkout in another, with no collisions.