Glossary

The five terms that carry the model are hall, repo, feature, promote and session. What is ivar explains them with an example; this page defines them and the rest in a line or two, so you can look one up when a command or a skill mentions it.

The model

Hall: a directory that owns a set of repos, features and sessions, defined by a committed ivar.json. The hall is itself a git repo, so a teammate gets yours with git clone and ivar sync. Keep one per scope of work: a team, a product, an initiative.

Repo: a git repository listed in ivar.json by name, URL and default branch. ivar clones it bare into .ivar/repos/<name>/.bare/, and every checkout, the default branch included, is a worktree of that clone.

Feature: one branch across the repos a change touches. Its name is the branch name. It outlives sessions and agents, because it is a file plus branches, not a conversation.

Promote: make a repo writable for a feature. ivar feature promote cuts the feature's branch in that repo (or adopts one that exists), creates its worktree and runs the repo's setup script. Demote removes the repo from the feature and leaves the worktree on disk.

Subfeature, child, parent: a feature created with --parent is a child. Its branch starts from the parent's branch, and its work lands there through integrate. A feature with no parent is a root; only roots deliver.

Provider: the agent harness a session runs: claude-code, opencode or omp. ivar init --provider picks the hall's default, ivar provider add adds another, and ivar session start --provider picks one for a session.

Manifest: ivar.json. It holds the hall's name, repos, providers, and optionally skills and MCP servers. It is parsed strictly: an unknown key is an error.

Sessions

Session: a view directory with an agent working in it, bound to at most one feature. Several sessions can share a feature and its worktrees.

View directory: the session's directory of symlinks, one per repo. A promoted repo points at the feature's worktree; every other repo points at its default-branch worktree, read-only. The harness config (.claude/, .opencode/, .omp/) and the instruction file live there too. $IVAR_SESSION_PATH names it.

Discovery session: a session with no feature. Every repo is read-only and promotion is off. /ivar-discovery opens one for exploring a problem.

Feature session: a session bound to a feature, with its promoted repos writable.

Convert: bind a discovery session to a feature, once. It cannot be undone.

Detached session: a session created without launching a provider, so an agent that is already running can use it. It stays until ivar session stop. A session that ivar session start launched ends when you quit the harness.

Relay: a fresh session on the same feature under a different provider, usually because the first one ran out of tokens. The branch, worktrees and plan carry over; the conversation does not.

Guard: what stops a session writing where it should not. Non-promoted repos have their write bits cleared, and the harness hook (plus Landlock on Linux) refuses writes outside the session's writable set.

Repos and refreshing

Sync: ivar sync brings the local hall in line with ivar.json: clones missing repos, writes harness config, runs setup scripts. It does not fetch.

Pull: ivar repo pull fetches and fast-forwards default branches. It never touches a feature worktree.

Setup script: .ivar/setups/<repo>.sh, committed with the hall. It prepares a fresh worktree: dependencies, codegen, env files. ivar runs it with bash on sync and on promote, and records a receipt so it re-runs only when the script changes. See setup scripts.

Session hook: .ivar/setups/<repo>.session.sh, run in each promoted worktree on every session start, for per-session state such as a local database.

Secrets directory: .ivar/secrets/, ignored by git and passed to scripts as IVAR_SECRETS_DIR.

Planning

Requirements, analysis, plan: the three planning artifacts under .ivar/features/<feature>/. Requirements say what must be true, analysis what the code looks like today, the plan how the change is built.

Approval gate: your explicit approval of one artifact, recorded with ivar plan approve. Approving records a fingerprint, so editing an approved artifact sends it back for approval. Integrate and deliver both check the plan gate.

Short path: writing only plan.md for a small change. A gate whose artifact was never written does not block.

Run receipt: the record /ivar-execute keeps under .ivar/features/<feature>/execution/: the plan it ran, each wave's checkpoint, and the outcome.

Delivering

Integrate: land a child's work on its parent's branch, one repo at a time, from the parent's session. Each repo's result is recorded in a receipt, so a failed run resumes where it stopped.

Deliver: push a root feature's branches and open or update one pull request per repo. --preview shows what would happen and prints a fingerprint; the apply step takes that fingerprint and refuses if anything changed since.

Land: ivar feature deliver --land fast-forwards each default branch to the feature and pushes it, instead of opening pull requests.

Close: end a feature with an outcome: delivered, integrated or abandoned. Delete removes its worktrees and state; prune deletes features whose work has landed.

Health

Doctor: ivar doctor diagnoses the hall: failed promotions, stale integrate staging, branches two features share, worktrees whose directory is gone. Each finding comes with a fix.

Stale: a repo's remote has commits its clone lacks. ivar repo pull catches up.

Degraded: a clone or worktree is missing. ivar sync repairs it.

Not supported

Windows, and Codex or Cursor as providers. ivar runs on Linux and macOS with Claude Code, OpenCode and OMP.