Quickstart
Install ivar, create a hall, explore it in a discovery session, and deliver a first feature from Claude Code, OpenCode or OMP.
Install ivar, create a hall on a repo you own, explore it in a discovery session, then take one feature from branch to pull request. The hall setup takes about fifteen minutes; the feature takes as long as the change does.
Before you start
- git, and read access to at least one repo you can clone.
- A harness: Claude Code,
OpenCode or OMP. Pick the one
you already work in; only the
ivar initflag and the command you launch differ. - Remote auth.
ivar repo addclones through your existing git remotes. For GitHub it reads a token from the GitHub CLI, so rungh auth loginfirst, or export$GITHUB_TOKEN/$GH_TOKEN.
Platform support
ivar runs on Linux and macOS. Windows is not supported, because a session's
view directory is built from symlinks; WSL is untested. The supported
providers are Claude Code, OpenCode and OMP. Codex and Cursor are not.
Nothing leaves your machine
ivar is a single binary that never talks to a server. It clones from the
remotes you already use and writes only inside the hall directory. Its one
unrequested request is a release check against GitHub, at most once per 20
hours — IVAR_NO_UPDATE_CHECK=1 turns it off.
Install
Fetches the release binary for your platform and verifies its checksum.
curl -fsSL https://ivar.run/install | shOn Arch Linux, the AUR package is ivar-bin (paru -S ivar-bin).
Verify
ivar --versionIf the shell cannot find ivar, the install directory is not on your PATH.
Start a new shell, or add it.
Keep it current
When a newer release is out, ivar ends a command with one line on stderr
saying so. Take it with:
ivar upgradeIt upgrades through whichever channel installed ivar — the install script or
cargo — and prints the command for a package-manager install instead of
running it.
Set up the hall
Pick your harness in the second step below; the rest is identical for every provider.
Create the hall directory
A hall is the directory that owns your repos and sessions. Make one and turn it into a git repo — the hall itself is version-controlled, because that is what lets a teammate reproduce it.
mkdir my-hall && cd my-hall
git initCreate the hall
Writes the hall record: ivar.json, .ivar/, and the hall's gitignore lines.
--provider picks the harness the hall is set up for. Leave it off and you
get a Claude Code hall.
ivar initThe hall takes its name from the directory; --name overrides that. The
provider recorded here becomes the hall's default. Add another later with
ivar provider add <name>.
You commit ivar.json. Most of .ivar/ is local working state that the
gitignore lines keep out of git, with two exceptions you do commit:
.ivar/setups/ (each repo's setup script)
and .ivar/skills/ (the hall's shared skills). Your teammates run what you put
there.
Add a repo
Declares the repo in ivar.json, clones it bare, and materialises its
default-branch worktree. <name> is one path segment, unique in the hall;
<url> is the git remote.
ivar repo add <name> <url>Or create a new repo in the hall's origin or on GitHub:
ivar repo create <name> --local
ivar repo create <name> --remoteThe default branch is main unless you pass --default-branch; ivar does
not read the remote's HEAD. If the repo's default branch is master or
develop, the worktree checkout fails on a missing main, so name it:
ivar repo add <name> <url> --default-branch master. Repeat the command for
every repo the hall should own. A hall with one repo is a normal
starting point: each feature still gets its own branch and worktree, so you
can run parallel features on one app before a second repo ever joins.
Check the hall
Before opening an agent on it, confirm the hall is what you expect. status
reports health and each repo's state; doctor diagnoses problems and suggests
fixes when it is not.
ivar status
ivar repo listOpen a discovery session
Launch your harness from the hall root, where ivar init put the /ivar-*
commands, and run /ivar-discovery in it.
cd my-hall && claude/ivar-discoveryThe command runs ivar session start for you. That creates a discovery
session: a view directory with every repo mounted read-only on its default
branch and no feature attached. Your agent keeps running at the hall root and
reads the repos through the session's path ($IVAR_SESSION_PATH), so you do
not need to restart it.
Discovery is read-only, so a toolchain that writes caches into the repo
(flutter pub get creating .dart_tool/, a build writing build/) can fail
there. Run builds in a feature session, where the repo is writable.
If a clone fails
ivar repo add clones from your remotes. For GitHub, ivar reads its token
from the GitHub CLI. Run gh auth login first, or export $GITHUB_TOKEN /
$GH_TOKEN. Every command also takes --json, which prints exactly the
value the command computed — useful when the human-readable error is not
enough.
What discovery does
The agent asks what you want to understand or decide, then explores the codebase without writing to it. Once it has a problem, an outcome, scope, affected repos and risks, it may offer to convert the session into a feature session. It asks first, and a conversion cannot be undone. You can also skip discovery and create the feature yourself, as below.
Your first feature
A feature is one branch across the repos a change touches. The glossary defines the terms this section uses.
Create it and promote a repo
ivar feature create add-currency
ivar feature promote add-currency <repo>create records the feature. promote cuts the add-currency branch in that
repo, gives it a writable worktree, and runs the repo's setup script there.
Open a feature session
ivar session start add-currencyThis launches the hall's default provider inside the feature's view
directory, with the promoted repo writable and every other repo read-only.
Pass --provider opencode or --provider omp to pick another provider the
hall lists.
Plan and build
In the session, run /ivar-plan. It writes the plan with you and stops at
each approval gate for your answer. Once you approve the plan, run
/ivar-execute to build it wave by wave. The planning
and execution guides cover both.
Deliver
Preview first. The preview pushes nothing and prints a fingerprint:
ivar feature deliver add-currency --previewApply with that fingerprint. It pushes the branch and opens a pull request:
ivar feature deliver add-currency --fingerprint <fp>/ivar-deliver runs the same two steps from inside the session. A pull request
needs a GitHub remote and gh logged in; with any other remote, delivery
pushes the branch and stops there.
Stop the session
Quitting the harness ends a session that ivar session start launched. A
session your agent started detached (as /ivar-discovery does) stays until
you stop it:
ivar session stop <SESSION_ID>Inside the session, ivar session stop with no id stops the current one.
Commands verified against ivar v0.13.0-dev+099fe251.
Share the hall
The hall is a git repo holding a committed ivar.json. Push it, and a
teammate gets the same repos on the same branches, with the same setup scripts
and MCP servers:
git clone <hall-url> my-hall && cd my-hall
ivar syncivar sync clones the missing repos, writes the harness config and runs the
setup scripts. Run it again after every pull of the hall.
One hall, or several?
A hall is cheap: it is a directory with a manifest. Teams usually keep one per product area, holding the repos that change together — not one per developer, and not one for the whole company.
Further reading
Per-harness reference — what each session materialises and how /ivar-discovery
runs there.
Claude Code
Config directory, init flag, and provider reference for Claude Code.
OpenCode
Config directory, init flag, and provider reference for OpenCode.
OMP
Config directory, hooks and extensions for OMP.