Workspaces (git worktrees)
Run a session or a subagent in its own git worktree, then merge, apply, open a pull request for or remove its work with venom workspace.
A workspace is a git worktree venom makes for a session or a subagent: its own checkout on its own branch, sharing the repository's history. Two sessions, or two subagents, can edit the same files without stepping on each other, and you decide later what lands. It works like Claude Code's --worktree and isolation: worktree.
venom -w demo # .venom/worktrees/demo on branch venom/demo, from HEAD
venom -w demo --from main # start from another branch, tag or commit
venom -w # a generated name (brisk-otter)
venom workspace list # what venom has made
venom workspace merge demo # land it on the branch it came fromWorkspaces are off by default. To start every interactive session in one, venom config set workspaces.default session.
A session in a workspace
venom -w [name] (or --worktree) moves into the worktree before anything else starts, so the working directory, the permission boundary (writes outside the worktree ask, the main checkout included), the OS sandbox's writable roots, checkpoints, the code index and the saved session all belong to it. venom -w demo again later reopens it. The HUD shows ⎇ venom/demo. --no-worktree skips the workspace once, whatever workspaces.default says.
When the session ends, a workspace with nothing in it (no uncommitted or untracked files, no commits its source branch lacks) is removed with its branch. One with changes is kept, and venom prints how to land it (venom workspace merge demo | pr | rm).
The first time, venom adds /.venom/worktrees/ to .git/info/exclude for this clone; your .gitignore is never edited.
Commands
The same commands work from the shell (venom workspace …) and in a session (/workspace …). ctrl+g W lists the workspaces; ctrl+g u commits and pushes the current one.
| Command | What it does |
|---|---|
list (default) |
Name, branch, ahead/behind its source branch, clean or dirty, files changed, last used, the session holding it. |
new [name] [--from <ref>] |
Make one without starting a session in it. |
switch <name> |
In a session: prints venom -w <name> to continue there (a running session can't change directory). |
diff [name] |
Its changes since it started. |
merge <name> [--squash] [--into <branch>] |
Commit what is uncommitted in it, merge its branch into the branch it came from (or --into), and remove it. Refused when that checkout has uncommitted changes, when another live session holds it, or on a conflict (checked first, so nothing changes). |
apply <name> |
Apply its changes to this working tree, uncommitted (three-way when needed). |
pr <name> [--remote origin] [--base <branch>] |
Push its branch and open a pull request with gh pr create --fill. The only command that uses the network. |
push [name] [--remote origin] |
In a session: commit and push the workspace's branch. |
rm <name> [--force] |
Remove it and its branch. Without --force, refused when it holds work. |
Add --json to any of them for machine-readable output. There is no tool for these commands, so the model can't merge, push or delete a workspace: only you run them.
Subagents in their own worktrees
A task call can ask for "isolation": "worktree", and so can an agent file's frontmatter. workspaces.default: subagents (or both) gives every writing subagent one; a task's "isolation": "none" opts out. Each child starts from your working tree as it is (uncommitted changes included) in a temporary workspace named task-<agent>-<id>, commits what it changed on its branch, and its report says the changes are not in your working tree. Land them with /workspace merge task-worker-3f2a1c or /workspace apply task-worker-3f2a1c; drop them with /workspace rm task-worker-3f2a1c --force. A child in its own worktree may only write its own branch, and its network is limited to the package registries unless its agent file says otherwise.
Configuration
| Key | Default | What it does |
|---|---|---|
workspaces.default |
off |
off: only when asked; session: every interactive session; subagents: every writing subagent; both. |
workspaces.dir |
.venom/worktrees |
Where workspaces go, relative to the repository root. |
workspaces.branch_prefix |
venom/ |
Prefix of each workspace's branch. |
workspaces.cleanup |
auto |
At session end: auto removes it when nothing would be lost, keep always keeps it, ask asks. |
workspaces.copy_ignored |
[.env.example] |
Gitignored files copied into a new workspace (gitignore patterns). A secret-named file (.env, a key) is copied only when a pattern names its exact path. .worktreeinclude is read too. |
workspaces.create |
none | Your command, run with sh -c in each new workspace (a database branch, a preview deploy). KEY=VALUE lines it prints go to .venom/worktree.env and the agent's environment there. A failure keeps the workspace and starts no agent. |
workspaces.finish |
none | Your command, run just before venom removes a workspace. A failure warns; the workspace is still removed. |
workspaces.timeout_ms |
120000 |
Kill create and finish after this long. |
create and finish get VENOM_WORKSPACE_DIR, VENOM_WORKSPACE_BRANCH, VENOM_WORKSPACE_NAME and VENOM_WORKSPACE_SOURCE. From a project's venom.yaml, dir, copy_ignored, create and finish need the project to be trusted.
workspaces:
default: session
copy_ignored: [".env.example", ".env"]
create: |
createdb "app_$VENOM_WORKSPACE_NAME"
echo "DATABASE_URL=postgres:///app_$VENOM_WORKSPACE_NAME"
finish: dropdb --if-exists "app_$VENOM_WORKSPACE_NAME"Safety
venom only touches worktrees it made: each is recorded under the repository's .git/venom/, and a worktree you made with git worktree add is never listed, merged or removed. A workspace a live session holds is locked and can't be merged, removed or reopened by another session. venom's own git calls run with the repository's hooks and filters switched off.
Troubleshooting
| Message | Cause and fix |
|---|---|
| merge refused: uncommitted changes | The checkout of the target branch has work in progress. Commit or stash it, or use apply. |
| merge refused: conflict | Resolve in the workspace (merge the target branch there), then merge again. |
| rm refused | The workspace has uncommitted files or commits not on its source branch. --force removes them. |
workspaces.default is session, but …; running here |
The directory isn't a git repository, or git failed; the session runs in place. |