ivar hall

A hall is a directory that owns a set of repos. It is itself a git repo, and the file it commits — ivar.json — is the only thing a teammate needs to end up with the same checkout you have.

Create one

mkdir acme-hall && cd acme-hall
git init
ivar init

ivar init writes ivar.json, the .ivar/ working area, and the hall's gitignore lines. It takes the hall's name from the directory unless you pass --name, and records claude-code as the sole available provider unless you pass --provider.

Add repos

ivar repo add api https://github.com/acme/api
ivar repo add web https://github.com/acme/web --default-branch develop

Each call declares the repo in ivar.json, clones it bare, and materialises its default-branch worktree. The name is one path segment and must be unique in the hall; the default branch is main unless you say otherwise.

{
  "name": "acme",
  "providers": {
    "available": ["claude-code", "opencode"],
    "default": "claude-code"
  },
  "repos": [
    { "name": "api", "url": "https://github.com/acme/api", "default_branch": "main" },
    { "name": "web", "url": "https://github.com/acme/web", "default_branch": "develop" }
  ],
  "version": 1
}

The layout on disk

One bare clone per repo. Every working copy — including the default branch — is a worktree cut from it.

Because these are worktrees and not copies, editing a file under .ivar/repos/ edits that repository. There is no export step and nothing to keep in sync.

Onboarding a teammate

git clone git@github.com:acme/hall.git && cd hall
ivar sync

ivar sync brings the local hall in line with ivar.json: it clones repos that are missing, materialises harness config, and runs each repo's setup script. Setup scripts are receipted, so a second sync does not re-run work that has already been done — --force-setup overrides that for when a script's effect was undone outside ivar, like a deleted node_modules.

Keeping it current

ivar repo pull            # fetch every repo's default branch
ivar repo pull api        # or just one
ivar repo setup api       # re-run one repo's setup script
ivar repo list            # what is declared, and its state

ivar repo remove takes a repo out of the manifest and tears its files down. It refuses while the repo is promoted in a feature or referenced by a live session; --force lifts both gates and cascades.

When something looks wrong

ivar status      # hall health, and each repo's state
ivar doctor      # diagnose problems and suggest fixes
ivar cleanup     # reconcile stale state (asks before deleting)

Every command accepts --json, which prints exactly the value the command computed — the human-readable output is a rendering of that same value, so a script and a person can never be told different things.

Providers

ivar provider list
ivar provider add opencode

The hall's providers decide which harnesses a session can be opened in, and which one ivar session start uses when you do not name one.