Quickstart

By the end of this page you’ll have a ticket that an agent picked up, worked on in an isolated branch, and handed back to you for review.

You need Volli installed, a git repository to point it at, and one coding-agent CLI on your machine.

1. Add a project.

   Press + in the project rail and pick a git repository on disk. That folder becomes the project’s main checkout. Ticket automation never writes to it.

   Volli derives a ticket prefix from the folder’s name, using the initials of its first three words, so volli-code becomes VC. The prefix starts every display ID on the board.

2. Write a ticket.

   Create a ticket and give it a title and a body. The body is the scope of the work, written in Markdown. The agent reads it as its opening instruction. Write it the way you would brief a colleague: what to change, where, and what “done” means.

   Pick the harness you want: Claude Code, Codex, or Opencode. Volli remembers your last choice for the next ticket.

3. Move it to Doing.

   Drag the card into Doing. Volli:

   • creates a git worktree for the ticket on a new branch, volli/<DISPLAY-ID>-<slug>, based on the ticket’s base branch
   • opens a terminal session inside that worktree
   • starts your chosen agent there, seeded with the ticket’s runtime brief

   Your main checkout is untouched. If you have another ticket already running, it keeps running in its own worktree on its own branch.

4. Watch it work, and step in when you want.

   The session is a real terminal, so you can type into it, answer the agent’s questions, redirect it, or stop it. The board tracks the ticket while you do.

5. Take it back for review.

   When the agent finishes, it reports back through the volli CLI and the ticket lands in Needs Review. Open the ticket to see what changed: the change set shows the ticket’s commits and working-tree changes against its base branch.

   If the work is wrong, send it back.

6. Ship it.

   The ticket has one button for getting the branch out, and its label changes to whatever comes next: Commit, then Push, then Create draft PR, then View PR. Press it as many times as the work needs. Volli opens the pull request as a draft, against the ticket’s base branch.

   Merging is yours. Volli watches the pull request and offers to archive the ticket once it lands.

Note

The push and pull-request steps shell out to the GitHub CLI, so they need gh installed and authenticated, and a remote to push to. Commit works without either.

Running more than one at a time

Move a second ticket to Doing and it gets its own worktree, its own branch, and its own session. Nothing is shared between them, so two agents editing the same file in two tickets never collide while working. Conflicts only show up at merge time, like with any two branches.

Next steps

The boardWhat each column means, and what's allowed to move a ticket between them.

Agents and worktreesHarnesses, sessions, branches, and what each ticket gets to itself.

CLI referenceEvery volli command, for you and for the agents you run.

ConceptsThe words Volli uses, defined once.