The app gives every task a durable place to run. Workspaces hold the broader context, projects connect repositories, and worktrees isolate branch-backed changes so agents can work in parallel without sharing a checkout.
Understand the hierarchy
Section titled “Understand the hierarchy”| Object | Use it for | What stays with it |
|---|---|---|
| Workspace | One company, client, or area of work | Projects, layout, theme, and scoped defaults |
| Project | One repository or folder | Branch rules, scripts, provider routing, and worktree location |
| Worktree | One branch-backed task | Files, Git state, tabs, processes, diff, and review context |
| Tab | One focused activity | A chat, terminal, file, diff, browser, or other tool |
| Shared Context | One feature spanning several projects | Shared instructions and related child worktrees |
The starred primary worktree is the checkout you opened or cloned. Use it for quick questions and small edits. Create a task worktree when an agent will make substantial changes or when several tasks may run at once.
Follow a task
Section titled “Follow a task”- Open a workspace and select a project.
- Create a task worktree from the right starting branch.
- Run an agent in Chat UI or its native terminal.
- Inspect the result against the recorded target branch.
- Commit, push, open a PR or MR, merge, and remove the finished worktree.
The workspace restores the task’s tabs, splits, processes, and review state when you return.
Choose your next topic
Section titled “Choose your next topic”- Learn the full relationship between workspaces, projects, and worktrees.
- Set the right base and merge destination with branches and targets.
- Coordinate related repositories with Shared Context.
- Run repository and agent work on another machine with remote workspaces.
- Open folders without branch workflows as non-Git projects.