Install Volli Code

Volli Code runs on macOS only. You can install the packaged app or build it from source. Volli is open source, so both give you the same working application.

Before you start

You need git installed, and at least one coding-agent CLI. Volli launches agents but doesn’t bundle or install them. Install whichever you plan to use:

• Claude Code
• Codex
• Opencode

Add the GitHub CLI if you want Volli to push branches and open pull requests for you. Everything else works without it.

Install the app

Download

Not released yet

The first packaged build ships at launch. Until then, the releases page is empty. Build from source.

1. Download the latest release from GitHub releases.

2. Open the downloaded file and drag Volli Code to your Applications folder.

3. Launch it from Applications.

Build from source

You need Node ^24.13.0 and pnpm 11.10.0. The repository pins both.

1. Clone the repository and install dependencies.

   git clone https://github.com/hussainph/volli-code.git
   cd volli-code
   pnpm install

   Installing also rebuilds Volli’s native modules against Electron’s ABI. That step runs on its own and takes a minute the first time.

2. Run the app.

   pnpm dev

   This starts the renderer with hot reload and relaunches Electron when the main process changes. Use it if you plan to change the code.

3. Or build once and run the built app.

   pnpm run build
   pnpm start

Tip

If pnpm install fails while compiling node-pty or better-sqlite3, run pnpm -C apps/desktop run rebuild:native. Those two are native addons and need rebuilding against Electron after any dependency change.

First launch

Volli offers to install the volli command and its agent skills the first time you open it:

Install the Volli CLI and agent skills? Adds the volli command to /usr/local/bin and installs its skill for the agents you already have.

Choosing Install asks for your admin password, because /usr/local/bin needs it. Choosing Not Now costs you nothing: the terminal sessions Volli opens have volli on PATH either way. Installing it puts the command in terminals Volli didn’t start, and gives your agents a skill describing how Volli expects them to use it.

You can run it later from File → Install Volli CLI & Agent Skills…, and undo it from File → Remove Volli CLI & Agent Skills….

The volli CLI

Volli ships a volli command that agents use to read tickets and report back. Every terminal session Volli opens has it on PATH, pointed at the running app through a local Unix socket.

You can run the same commands yourself from any session terminal:

volli identify

If that prints the current project and ticket, the app and the CLI are talking to each other. See the CLI reference for everything it can do.

Where Volli keeps your data

Everything is local:

• Projects, tickets, labels, and the event log live in a SQLite database in Electron’s userData directory.
• Ticket worktrees live under ~/.volli/worktrees/.
• Terminal transcripts are files on disk, indexed alongside the database.

Removing a project from Volli never touches the folder on disk.

Next steps

QuickstartAdd a project, write a ticket, and watch an agent pick it up.

TroubleshootingNative module errors, agents that won't start, and CLI connection failures.