OpenCode
Create a hall, add a repo, and open your first discovery session in OpenCode.
Set up the hall
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-hallgit initCreate the hall
Writes the hall record: ivar.json, .ivar/, and the hall's gitignore lines. ivar.json is the part you commit; .ivar/ is local working state and is ignored for you.
ivar init --provider opencodeThe hall takes its name from the directory — --name overrides that. The provider recorded here becomes the hall's default; add more later with ivar provider add.
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>The default branch is main unless you pass --default-branch. Repeat the command for every repo the hall should own — a hall with one repo is valid, it just has nothing to span yet.
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 statusivar repo listOpen a discovery session
In OpenCode, run /ivar-discovery. It starts a guided discovery session, with no feature attached yet — every repo mounted read-only on its default branch.
/ivar-discoveryThe session gets its own view directory with the repos at the root and .opencode/ materialised for OpenCode, so the agent starts with the hall's skills and context already in place.
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 happens next
The agent asks what you would like to understand or decide, then explores the codebase read-only. Repos are never written to during discovery. Once it has a problem, a desired outcome, scope boundaries, affected repos, and risks, it may offer to convert the session into a Feature Session. Conversion is offered, never automatic, and it is irreversible.
After conversion the feature's repos become writable, and /ivar-plan turns the discovery brief into a plan. From there the feature has its own loop: ivar feature promote brings another repo onto the branch when the work turns out to reach further than you thought, and ivar feature deliver pushes each promoted worktree and opens its pull request. Both are beyond this quickstart.
Commands verified against ivar 0.0.0.