Troubleshooting

I cannot start a structured Session

Choose a default model in Settings → Model Access. If no model is selected, Volli refuses to start the Session rather than selecting one for you.

If a provider is unavailable, open Model Access and use its recovery action to sign in again or refresh availability. The page lists only the models Volli can use without exposing credentials.

volli exits with code 3

The local CLI could not reach the running app.

1. Check that Volli is open.
2. Run volli identify from the terminal companion.
3. Check that the terminal has VOLLI_SOCKET set.

Volli sets the socket context for terminal companions it starts. A terminal you open elsewhere may need the CLI installed and connected separately.

volli: command not found

Open Settings → CLI to see which executable and shell integration Volli detected. Run Doctor, then use Fix & Re-run to regenerate the parts Volli owns. Terminal companions opened by the app already receive volli on PATH.

pnpm install fails on a native module

The development build uses native modules that must match Electron’s ABI. Run:

pnpm -C apps/desktop run rebuild:native

Then run pnpm install again if needed.

My ticket worktree is still on disk

Archiving a ticket retains its worktree, and Volli refuses to remove a worktree with uncommitted work. Use Remove worktree… from the ticket context menu after the branch is landed, or remove it yourself:

git worktree remove ~/.volli/worktrees/<project-dirname>-<short-id>/<TICKET-ID>-<slug>

For tickets in Done, Settings → General → Done worktree retention controls when Volli can reclaim a clean folder automatically. Keep worktree exempts a ticket from that cleanup.

A shortcut does nothing

Terminals can claim keystrokes before the app does. Click outside the terminal companion and try the shortcut again.

Single-letter shortcuts are suppressed while you are typing in a text field, editor, or dialog.

The terminal does not follow my app theme

A named theme in your Ghostty configuration takes precedence over Volli’s generated colors. Remove the theme key from Ghostty and Volli terminal settings if you want the terminal to follow the app theme. See Theming.

Where Volli keeps things

• Database: projects, tickets, labels, and local history in a SQLite file in Electron’s userData directory.
• Worktrees: ~/.volli/worktrees/.
• Session transcripts: files on disk, indexed locally.

Removing a project from Volli does not remove its folder from disk.

Report a bug

Include the output of volli identify and the steps that led to the problem in a GitHub issue: hussainph/volli-code.