Skip to content

Chats and worktrees

Use a Board chat to shape project-wide work before it has a ticket. Start a ticket chat when you know which task to work on. A ticket chat can work in its own Git worktree, so changes stay on separate branches. See Use a chat to start and reopen a chat.

Chat Use it for Working directory
Board chat Project work that is not scoped to one ticket The project’s main checkout
Ticket chat One ticket and its brief The ticket’s worktree, or the main checkout if you choose Project checkout

Choose a default model in Settings → All projects → Models before you start a built-in chat. A ticket’s destination can be changed between New worktree and Project checkout until its first worktree is created.

Moving a ticket to Doing records its status. It starts a Run only if an enabled Automation is armed for that column. Starting a chat is always a separate action.

When a ticket uses a worktree, its first Session creates a separate Git worktree on a branch named volli/<DISPLAY-ID>-<slug>, such as volli/VLT-12-mcp-server. Volli stores ticket worktrees under ~/.volli/worktrees/.

The base branch comes from the ticket’s setting, the project’s Configure → Worktrees setting, or the branch Volli detects. Creating a worktree uses the refs already on your machine; it does not fetch first.

In Configure → Worktrees, Branch from sets the default base branch. Setup command sets a setup command, such as pnpm install. The setup runs once in each new worktree, before the agent starts, whether the first Session there is a chat or a terminal. A terminal runs it in its shell, where you can watch it. A chat runs it in the background and starts once it finishes; if it fails or runs longer than nine minutes, the chat does not start, and the ticket’s activity shows the exit code and the end of the output. The setup does not run again when Volli reuses an existing worktree, including after a failed setup, so a retry starts the agent without it.

Git brings tracked files into a new worktree. Volli also copies selected local files from the main checkout. By default, these are .env* and .claude/settings.local.json.

Add your own patterns to a .worktreeinclude file in the repository root. Later patterns take precedence, and a !pattern line excludes a match. Volli does not replace a file that already exists in the worktree, nor refresh a copied file on later Sessions.

An agent can read the copied local configuration, including credentials in an environment file. Review which files get copied before you start work.

For example, add a pattern and exclude a file the defaults would copy:

config/local.json
!.env.production

.worktreeinclude extends the built-in defaults; it does not replace them.

You can inspect a ticket branch from a terminal companion:

volli worktree status VLT-12
volli worktree diff VLT-12

worktree diff compares the ticket branch with its base. With --working-tree, it shows uncommitted changes instead.

To merge an available base ref into the ticket branch, run volli worktree sync VLT-12. Sync does not fetch, wait for checks, or resolve conflicts for you. It leaves a conflicted merge in place; volli worktree sync VLT-12 --abort undoes that merge. See Review ticket changes for the Diffs rail and repository actions.

Separate branches can still change the same files. Run volli conflicts to find paths touched by multiple active worktrees.

A chat’s history remains available when you navigate away or reopen Volli. See Use a chat to return to an existing Session.

An Automation Run creates a fresh Session; it does not resume an existing chat. See Automations for Triggers and Run history.

A terminal companion is a manual shell workflow alongside built-in chat. See Terminal companions and the CLI reference.

A ticket’s Change Set includes committed and uncommitted changes relative to its base branch. Archiving keeps the worktree. A later cleanup can remove the checkout while keeping the branch, ticket, and history.

Follow Review and publish changes to land the work, then Clean up worktrees for retention and removal.