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

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.