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.
Board chats and ticket chats
Section titled “Board chats and ticket chats”| 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.
Ticket worktrees
Section titled “Ticket worktrees”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-12volli worktree diff VLT-12worktree 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.
Chat history
Section titled “Chat history”A chat’s history remains available when you navigate away or reopen Volli. See Use a chat to return to an existing Session.
Automation Runs and Sessions
Section titled “Automation Runs and Sessions”An Automation Run creates a fresh Session; it does not resume an existing chat. See Automations for Triggers and Run history.
Terminal companions
Section titled “Terminal companions”A terminal companion is a manual shell workflow alongside built-in chat. See Terminal companions and the CLI reference.
Change sets and retained worktrees
Section titled “Change sets and retained worktrees”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.