Workspaces and worktrees
What a workspace is, how it's named, where it lives, and what archiving keeps.
A worktree per task
A git worktree is a second checkout of the same repository, in a folder of its own, on its own branch. All worktrees share one .git, so creating one is quick and takes little space, and commits in one are visible in the others.
Compagnion gives every task such a worktree. That's what makes parallel agents safe: each one edits its own files, runs its own build and commits on its own branch. Your own checkout of the project is never touched.
A workspace is that worktree plus everything around it: its sessions with agents, its terminals, its pull request and its history.
Names and branches
- A workspace created from a description gets a title and a branch name from a small model, such as
vincent/fix-recipe-search. The branch is renamed only until it's pushed. - A workspace for a GitHub issue is named after the issue:
42-recipe-search-ignores-accents, the same name GitHub uses for Create a branch on an issue. A branch that already exists there is picked up instead of made again. - A workspace from a branch or pull request uses that branch.
Under Settings → Git you choose the prefix (your GitHub login, your own, or none) and whether the model may rename branches and title workspaces.
A plain git push in a workspace sets the upstream by itself, so you or the agent never need --set-upstream.
Where they live
Worktrees go in ~/.compagnion/workspaces/<project>/<workspace>, or in the folder you set under Settings → Advanced. Changing that folder only affects new workspaces; existing ones keep working where they are.
Status
A workspace's status follows its pull request:
| Status | When |
|---|---|
| In progress | No pull request yet |
| In review | An open or draft pull request |
| Done | Merged, also when the agent merged the branch itself without a pull request |
| Canceled | The pull request was closed |
Dashboard, at the top of the sidebar, shows every workspace as a card in a column per status, with its branch, +N −M, the agent's last reply and the next step.
Archive and restore
When you're done with a workspace, archive it. Compagnion stops its sessions and terminals, keeps any uncommitted work as a snapshot, removes the worktree and leaves the branch. The history stays readable under Archived.
Restore brings it back: the worktree on its branch (recreated from the snapshot if the branch is gone), your uncommitted work as it was, and the setup script runs again.