Settings and configuration
Volli splits configuration into two places: Settings, for preferences that apply everywhere, and Configure, for defaults scoped to one project. This page covers every pane in both, and the one path for backing up your data.
Settings
Section titled “Settings”Open Settings from the gear icon in the sidebar footer.
General
Section titled “General”Settings → General → Done worktree retention sets how long Volli keeps a finished ticket’s checkout. It defaults to 14 days and accepts whole numbers of 1 or more.
After a ticket has spent that long in Done, Volli can remove its clean worktree folder when no pull request is open and no work is running there. The ticket, branch, commits, and pull-request URL remain, and you can recreate the worktree from the branch. The same setting controls when clean orphaned worktree folders become eligible for cleanup.
Appearance
Section titled “Appearance”Settings → Appearance has three sections. App theme holds the light/dark/auto mode and the canvas editor; see Theming for both. Editor and Terminal are covered here.
Editor. The syntax-highlighting theme for the editor Volli uses for files and documents. It doesn’t follow your canvas. Leave it alone and the row shows Default; pick one explicitly and it shows Set by Volli, with a button to reset it.
Terminal. Font family and font size, plus the terminal’s color theme (covered in Theming). Each row shows where its value came from: Inherited from Ghostty, Set by Volli, Set by this project, or Built-in default, with a revert button on anything Volli set. Reverting removes the key from Volli’s overlay file rather than touching your Ghostty config. Two buttons under Config files reveal the Ghostty config and Volli’s overlay file in Finder.
Model Access
Section titled “Model Access”Settings → Model Access holds the model policy for structured Sessions. Choose separate defaults for Project chats, Ticket Sessions, and Utility work; Ticket Sessions and Utility inherit the Project chats default until you choose one explicitly. Automatic compaction controls whether Sessions compact before their context window fills, and each visible model can set its own reserve. Visible models controls which available models appear in every composer and picker. The Accounts section shows which providers are available and gives you a recovery action when sign-in is required. Volli never silently substitutes a different model or account.
Settings → Web selects the provider used by structured Sessions for web search. Choose Off, Brave, Exa, or SearXNG. Brave and Exa store the API key in your macOS keychain and never read it back into the renderer. SearXNG stores the instance URL you provide.
Harness Runtimes
Section titled “Harness Runtimes”Settings → Harness Runtimes lists the terminal companions Volli can launch: Claude Code, Codex, Cursor, and OpenCode, plus registered custom harnesses. These settings describe manual terminal integrations, not the Pi-backed structured runtime configured under Model Access.
Settings → CLI shows which volli executable and shell integration are in
use. Run Doctor checks the live installation. Fix & Re-run regenerates
wrappers, harness configuration, and shell integration before checking again.
Worktrees
Section titled “Worktrees”Settings → Worktrees lists orphaned worktree directories: leftovers from tickets that no longer exist, kept on disk because git found uncommitted changes, an unfinished merge, or commits that never reached a remote. Volli never deletes these automatically. Each row gets Reveal in Finder and Delete. Deleting is permanent and asks you to confirm first.
Volli sweeps for orphans once, at app launch, and caches the result. Press the refresh button to rescan on demand, for instance after you’ve committed and pushed the work yourself.
Configure
Section titled “Configure”Open the Configure tab for a selected project. Everything here is scoped to that one project.
General
Section titled “General”Configure → General → Default base branch overrides which branch a new
ticket’s worktree branches from. Leave it blank and Volli detects your repo’s
default itself, from origin’s HEAD, or your current branch if there’s no
remote.
Configure → General → Setup command runs once in a fresh ticket terminal,
after its worktree is created and before a terminal harness starts. Use it for
pnpm install or another command the worktree needs. Output stays in that
terminal. If setup fails, the harness does not start and the terminal remains
open so you can fix it by hand.
Appearance
Section titled “Appearance”Configure → Appearance lets this project override the app-wide canvas, the light/dark choice, and the terminal theme, each on its own. The editor follows the resolved light/dark choice automatically. Covered in Theming.
Worktrees
Section titled “Worktrees”Configure → Worktrees documents the copy set: which files, besides your
tracked source, reach a fresh ticket worktree. By default that’s .env* and
.claude/settings.local.json, copied with their real contents so an agent has
your local secrets and settings without either being committed to the repo.
Add a .worktreeinclude file at your project’s repo root to change the set. It
uses gitignore syntax, one pattern per line, and Volli reads it straight from
your main checkout, so it never has to be tracked by git itself:
# Extend the default copy set.env.localconfig/dev-secrets.json
# Suppress a default: stop .env* from being copied!.env*The copy step follows three more rules:
- It fires once, right after
git worktree add, before the setup command or the agent starts. - If a file already exists at the destination, because
git worktree addput it there, Volli leaves it alone. This step only fills in what git doesn’t track. - Volli recreates a symlink as a symlink rather than following it, so a link pointing outside your repo can’t leak its target’s contents into the worktree.
Back up your data
Section titled “Back up your data”Volli does not sync its local database. File → Export Database as JSON… writes your projects, tickets, labels, event history, Sessions, and comments to a JSON file at a location you choose. There’s no import path back in, so treat the export as a backup and inspection tool rather than a restore mechanism.