# Vago

> Vago runs your Workflow on a Goal in your repo, one Ticket at a time, and leaves you a PR.

Each link is the Markdown copy of a page on the site.

## Docs

- [Install](https://vago.buenomini.com/docs/install.md): Install vago with Homebrew or a release binary, or build it from source.
- [Set up a Project](https://vago.buenomini.com/docs/set-up-a-project.md): Run vago init in a repo to get the starter Workflows and skills, keep them current with vago update, and pick a Workflow.
- [Your first Goal](https://vago.buenomini.com/docs/your-first-goal.md): Write a Goal, add two Tickets, run it with vago run, and review the pull request it opens.
- [Goals and Tickets](https://vago.buenomini.com/docs/goals-and-tickets.md): The goal.md and Ticket file formats, how blockers order Tickets, and giving one Ticket its own Workflow.
- [Workflows](https://vago.buenomini.com/docs/workflows.md): Write a Workflow, the TOML list of agent and shell Steps every Ticket goes through, with Goal Steps, prompts, outputs, Harnesses and models.
- [Running and watching](https://vago.buenomini.com/docs/running-and-watching.md): Run a Goal with vago run, read what it prints, follow every Goal in the TUI, and read the Goal report its PR carries.
- [Planning a Goal in the TUI](https://vago.buenomini.com/docs/planning-a-goal.md): Plan a Goal with an agent in the TUI, read its Proposal in the Preview, choose the Workflow and accept it as a Goal with its Tickets.
- [When things go wrong](https://vago.buenomini.com/docs/when-things-go-wrong.md): What Vago does when a Step fails or vago run dies, what you see in vago run and the TUI, and how to pick a Ticket up, start it over or read its logs.
- [CLI reference](https://vago.buenomini.com/docs/cli-reference.md): Every vago command with its arguments, flags and an example, as its --help prints them.
- [Glossary](https://vago.buenomini.com/docs/glossary.md): The words Vago's code, docs and TUI use, each with what it means and the words it replaces.

## Cookbook

- [Cookbook](https://vago.buenomini.com/cookbook.md): Example Workflows, each a short TOML file you copy into .vago/workflows/ and change.
- [Chain Goals back to back](https://vago.buenomini.com/cookbook/chain-goals.md): An after_all Step that merges the Goal's PR, pulls the main checkout and starts vago run on the next Goal in a queue.
- [Solo: merge straight to main](https://vago.buenomini.com/cookbook/solo.md): A Workflow with no PR, which squash-merges each Ticket on the Goal's branch and fast-forwards main to it when the Goal ends.
- [Review on Codex](https://vago.buenomini.com/cookbook/review-on-codex.md): Claude Code builds each Ticket and Codex reviews it, by giving the review Step its own harness and model.
- [Your own check Step](https://vago.buenomini.com/cookbook/your-own-check.md): Run your Project's lint, typecheck and tests in the check Step, every one even when an earlier one fails, for the review Step to read.
- [Contribute to someone else's repo](https://vago.buenomini.com/cookbook/contribute-to-open-source.md): Run Goals in a repo you don't own with no Vago file, Goal, prompt or Run report in any commit or PR.
- [Give one Ticket another Workflow](https://vago.buenomini.com/cookbook/one-ticket-another-workflow.md): A Workflow for one Ticket of a Goal, such as a docs Ticket in a Goal of code Tickets, named with vago ticket add --workflow.
- [Run Steps once per Goal](https://vago.buenomini.com/cookbook/once-per-goal.md): before_all Steps that set up the Goal's worktree before its first Ticket, and after_all Steps that run once every Ticket is done.

## Agents

- [For agents](https://vago.buenomini.com/agents.md): Pages for a coding agent working in a repo that uses Vago, and a snippet for that repo's AGENTS.md that points the agent to them.
- [What Vago is and isn't](https://vago.buenomini.com/agents/what-vago-is.md): What Vago does in a Project, what it leaves to the Workflow and the human, and the words it uses.
- [Writing a Goal](https://vago.buenomini.com/agents/writing-a-goal.md): Rules for the goal.md an agent writes, which every agent Step of every Ticket reads with no human to ask.
- [Splitting a Goal into Tickets](https://vago.buenomini.com/agents/splitting-into-tickets.md): Rules for cutting a Goal into Tickets that agents build one at a time, each reading only the Goal and itself.
- [Writing a Workflow and its prompts](https://vago.buenomini.com/agents/writing-a-workflow.md): Rules for a Workflow file and the prompts of its agent Steps, which run with no human to answer a question.
- [Commands to run and to leave](https://vago.buenomini.com/agents/commands.md): Which vago commands an agent runs on its own, and which it leaves to the human, with the reason for each.
- [Limits](https://vago.buenomini.com/agents/limits.md): What Vago Alpha doesn't do, so an agent doesn't plan a Goal or Workflow around it.