---
title: Workspaces (git worktrees)
description: 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.
section: cli
order: 80
audience: [user, operator]
sources: [docs/workspaces.md, cli/src/workspace.ts, packages/harness/src/workspaces/index.ts, packages/harness/src/extensions/workspace.ts]
features: [cli.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`.

```bash
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 from
```

Workspaces are off by default. To start every interactive session in one, `venom config set workspaces.default session`.

## A session in a workspace {#session}

`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 {#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 {#subagents}

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 {#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.

```yaml
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 {#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 {#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. |
