Tutorials

The guide explains combo one concept at a time. These pages start from the other end: each one sits you in front of pi with a problem people are having with agents right now, and has you run the thing that answers it. Every page ends with the question it could not answer, and the next page opens on it, so they read in order and each one is short.

Everything runs on this repository. Clone it, install, load the extension, and nothing has to be copied anywhere:

git clone https://github.com/AI-for-dev/combo && cd combo
npm install
pi -e extension

You need a model pi can reach. The frames shown here were drawn by a real pi, 0.85.1, with every subagent on one small open-weight model served locally. A slow, cheap model is where every weakness shows, and none of what follows depends on a strong one. Where a page quotes a number, it says what kind of model produced it; the model column of a frame reads provider/model, because the one these pages ran on is not the one you will have.

The twelve

Reading. The session’s context is the scarce thing, and every page here spends someone else’s instead.

  1. A scout reads twenty files so you do not have to - the first subagent, and what your own window looks like afterwards.

  2. Three scouts, one answer - /run explore: the reading in parallel, the answer in your conversation, a failed branch shown rather than dropped.

  3. Keep the session out of it - /step: a chain walked by hand, an agent or a whole flow per step, with the main model told nothing until you say so.

Writing definitions. Agents and flows are data; our code decides what runs next. Both are files you can read in a diff.

  1. Write the chain down - your first flow, what it cannot say, and what a typo costs.

  2. An agent that cannot do harm - your first agent in .pi/agents/, why its toolset is the boundary and its prompt is not, and why a repository’s agents are third-party instructions.

  3. Teach it a house rule - a skill the reviewer opens itself, resolved nearest first.

Writing code. Agents that argue, and code that runs before anyone signs.

  1. Two agents arguing until LGTM - the loop, the two lifetimes, why reaching the cap is not success, and what a verdict is.

  2. Reading code is not running it - /run build: a run nobody has to sit through, the check whose verdict is final, and the resume.

  3. Two coders, one tree - why several writers get a copy each, patches landed one at a time, and nothing rolled back.

Running it for real. What it cost, how to stop it, and what the numbers are worth.

  1. Watch the meter - the turn that made 79 calls to a tool that did not exist, and the three ways to end one.

  2. Same work, two models - an A/B from the prompt line, then the honest version: M models, N repetitions, one table.

  3. A subagent that splits its own task - delegation, its depth, and a bill shaped like a tree.