Install Volli Code

Volli Code is a local-first macOS workspace for parallel coding agents. Install it, add a project, choose a model, and start your first chat.

In Volli, a task is a ticket. You can create tasks yourself or use an agent to help turn a broad idea into focused work.

What you need


Mac	Apple silicon (M1 or later). No Intel or universal build yet.
macOS	12.0 Monterey or later.
Git	Installed, with your repositories on disk.
A model	An account with a model provider, set up on first launch.

Volli itself needs no account.

Install it

Download the .dmg from volli.app/download, drag Volli Code to Applications, and open it.

If macOS blocks the app, the download was damaged. Delete it and download again.

Updates

The app installs a newer alpha when you quit. To stay on a specific build, download that release’s .dmg from GitHub Releases and replace the app in Applications.

Start your first chat

Add a project.

In the project rail, select +, then choose a git repository. That folder becomes the project’s main checkout. Volli derives a ticket prefix from the folder name, so a project called harbor gets tickets such as HB-1.
Choose a model.

Open Settings → Model Access, sign in to your provider, and pick a default model. Volli never silently switches to a different one.
Start a chat.

Select Chat. On Home, this starts a project chat in your main checkout. Use it to shape a broad idea or create tasks. Inside a ticket, Chat starts a ticket chat with the task’s brief and scoped context.

Continue with the Quickstart to turn an idea into tasks, run one task, and inspect the change.

Chats and terminals

A chat is Volli’s built-in way to run an agent. Use a project chat to plan broad work. Use a ticket chat when one task is ready to implement.

A terminal is a manual companion: a shell in the ticket’s worktree where you drive Claude Code, Codex, OpenCode, or your own TUI. Open it from the caret beside Chat. Volli never opens one as a fallback.

The `volli` CLI

Terminals Volli opens already have the volli command on PATH. To see what a terminal is attached to:

volli identify

Check the installation or run Doctor in Settings → CLI. Full command set in the CLI reference.

Where your data lives

Projects, tickets, and history: ~/Library/Application Support/Volli Code/
Ticket worktrees: ~/.volli/worktrees/
Chat transcripts: on disk, indexed locally

Model requests go to the provider you selected. Nothing else leaves your machine. Removing a project from Volli does not delete its folder.

Uninstall

Quit Volli Code and drag it from Applications to the Trash.

Remove its application data:

rm -rf ~/Library/Application\ Support/Volli\ Code

Remove any worktrees Volli created. These are git worktrees inside your own repositories, so remove them through git rather than deleting the folder:
Terminal window
```
ls ~/.volli/worktrees/
```
For each one you no longer want, run git worktree remove <path> from the repository it belongs to. Uninstalling does not touch your project folders.

Build from source

You can also run the development build. You need a Mac, git, Node ^24.13.0, and pnpm 11.10.0. The repository pins both versions.

Clone the repository and install dependencies.

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

Start the development app.
Terminal window
```
pnpm dev
```
This runs the renderer with hot reload and relaunches Electron after main process changes.
To run a built copy instead:
Terminal window
```
pnpm run build
pnpm start
```

Getting help

Something broken or confusing: open an issue.
Something security-sensitive: use private vulnerability reporting instead of a public issue.
Something not working on your machine: start with Troubleshooting.

Next steps

QuickstartTurn a rough idea into tasks, run an agent on one, and inspect the change.

ConceptsTranslate task, chat, branch, and review into Volli's UI terms.

TroubleshootingModel Access, CLI connection, and source-build problems.

All docs as plain text