Projects and workspaces
A project is a git repository on a host. A workspace is one place inside that project where agents and terminals work: either the project folder itself or a separate git worktree. The sidebar lists projects with their workspaces under them.
Add a project
Select Add project at the bottom of the sidebar, or press Cmd+O (Ctrl+O on Windows and Linux). Type to search folders on the host, select Browse…, or paste a path and select Open path.
Create a workspace
Press Cmd+N or select New workspace on a project. The form has:
| Field | What it does |
|---|---|
| Project, Host | Where the workspace lives. |
| Isolation | Local works in the project folder. New worktree creates a separate checkout on a new branch, so several agents can change the code at once without colliding. |
| Start from | The branch or pull request the new worktree starts from. |
| Title (optional) | The name shown in the sidebar. |
| What to launch | Chat starts an agent, Terminal opens a shell. Manage profiles edits saved launch settings. |
Select Launch to create the workspace.
Zekoder workflow commands create their own worktrees for plans and coding tasks. You do not need to create them by hand.
Organize the sidebar
Open the sidebar's display preferences to change:
- Grouping: by Project, Status, or Labels.
- Title: show the workspace title or the branch name.
- Show: which details appear on each row (branch, host, pull request, checks, diff stats, last activity, and more).
- Show background: include workspaces that agents created in the background.
When grouped by status, workspaces sort into Needs input, Failed, Ready to review, Working, and Done.
Right-click a workspace, or open its menu, to copy its path or branch, rename it, or Pin to top. Press Cmd+1 to Cmd+9 to jump between workspaces.
Archive a workspace
When the work is merged, archive the workspace from its menu or with Cmd+Shift+Backspace. Archiving a worktree that Zekoder created removes the worktree and closes its agents and terminals. If an agent is still running, Zekoder asks first.
A Local workspace is your project folder, so it cannot be archived. Use Hide from sidebar instead; nothing on disk changes.
Archived agents stay available under History in the sidebar.