One feature, three repos: a walkthrough

A field that crosses three repos

You need to add a currency to invoices. The API has to store and return it, the web app has to show it, and somewhere in between a shared types package describes what an invoice looks like. Three repositories, one change.

Why a single agent session across repos matters is covered in the context problem nobody solved. This post is the practical side: the commands, in order, for one feature that touches all three.

The hall

Register the three repositories in the hall:

ivar repo add api git@github.com:acme/api.git
ivar repo add web git@github.com:acme/web.git
ivar repo add types git@github.com:acme/types.git

Each one lands in ivar.json under repos. That file is the hall's manifest: which repos exist, where they come from, which harnesses and MCP servers every session gets. Nothing is promoted yet, so every repo sits on its default branch, read-only.

One feature, two repos to start

Create the feature and promote the two repos you know you need:

ivar feature create billing-currency
ivar feature promote billing-currency api
ivar feature promote billing-currency web

Promoting a repo cuts a billing-currency branch in it and gives it a worktree the feature can write to. types stays on its default branch as read-only context.

Start a session:

ivar session start billing-currency

One session sees both promoted repos side by side, plus types as read-only. The agent can change the API handler and the web component in the same conversation, and it can read the shared types to see what an invoice looks like today.

Scope grows mid-way

Halfway through, the agent reports the obvious: the invoice type lives in types, and both the API and the web app import it. The currency field has to go there first, or the other two changes won't compile against each other.

You don't need to stop the session or start over. From another terminal, promote the third repo:

ivar feature promote billing-currency types

types gets its own billing-currency branch and worktree, and the session can now write to it. The agent adds the field to the shared type and carries on with the API and the web app. The features guide covers promotion in more detail.

Where things stand

Check the feature:

ivar feature status billing-currency

Feature `billing-currency` (branch: billing-currency):
  api  ready  worktree present  base: main
  types  ready  worktree present  base: main
  web  ready  worktree present  base: main

Three repos, one branch name, each based on its own main. No list of branches to keep in your head.

Delivering together

When the work is done, preview the delivery:

ivar feature deliver billing-currency --preview

The preview writes nothing. For each promoted repo it reads the branch, the remote, the base and any existing pull request, then computes one fingerprint over all three. If any repo changes after you read the preview, the fingerprint no longer matches and apply refuses.

Apply it with the fingerprint the preview printed:

ivar feature deliver billing-currency --fingerprint <fp>

That pushes the billing-currency branch in each repo and opens the three pull requests together, each with a comment linking its siblings, so a reviewer on the web PR can find the API and types PRs.

Creating pull requests needs GitHub remotes. With local remotes, delivery only pushes. The delivery guide covers updating existing pull requests and delivering a subset of repos with --only.

What you didn't do

Cloning, branching, cross-linking pull requests and re-explaining context to fresh sessions were all handled by the feature, including when the scope grew mid-way.

Related

• One repo, many agents: parallel features from a Figma prototype — the single-repo counterpart, with subfeatures and one pull request.
• MCP servers in a hall — declare MCP servers once and every session across the three repos gets them.
• Quickstart — create a hall and your first feature.