# ivar
**Multi-repo worktrees for coding agents.** One feature across repos, as one unit: one branch, one plan, one pull request per repo, inside the Claude Code, OpenCode or OMP session you already use.
```sh
curl -fsSL https://ivar.run/install | sh
```
Add an `avatarUrl` field to the user profile: the agent describes it in `shared-types`, returns it from `api` and renders it in `web`, with all three mounted as real git worktrees on the `avatar-url` branch. Repos you haven't promoted are guarded (kernel-enforced on Linux; see [Limitations](docs/reference/limitations-sessions.md)).
- **Your harness:** Claude Code, OpenCode or OMP, with MCP servers declared once in `ivar.json` (`ivar mcp add figma`).
- **Plan first:** `/ivar-plan` stops for your approval after requirements, analysis and plan.
- **Code graph:** one local SQLite graph of every repo. In a two-repo benchmark, discovery took a median 460k tokens instead of 738k.
- **On your disk:** single Rust binary, Apache-2.0, no account, macOS and Linux. Pull requests go through `gh`.
[Quickstart](https://ivar.run/docs/quickstart) · [Docs](https://ivar.run/docs) · [Why not just git worktree?](docs/why-not-worktree.md)
## The model
`ivar` is a local Rust CLI built around five small ideas:
1. **Hall** — a committed directory that declares the repositories a team works
across in `ivar.json`.
2. **Feature** — one branch name shared by the repositories participating in one
change.
3. **Promotion** — the explicit decision to make a repository writable on that
feature. Everything else stays guarded read-only (kernel-enforced on Linux).
4. **Session** — a view directory opened for you or an agent.
5. **View Dir** — symlinks to the right real worktrees: feature worktrees for
promoted repositories, and for the rest the feature's base (the parent's worktree, the root's base branch, or the default branch).
```text
Hall
api ────────── promoted ──► avatar-url worktree (writable)
web ────────── promoted ──► avatar-url worktree (writable)
shared-types ─ promoted ──► avatar-url worktree (writable)
infra ────────────────────► main worktree (read-only)
│
▼
Session / View Dir
api · web · shared-types · infra · plans
```
From the view dir, one agent session describes the field in `shared-types`,
returns it from `api` and renders it in `web`. The plan, branches, and
worktrees remain on disk when the conversation ends.
## Why not just `git worktree`?
Use `git worktree` directly when one repository is the problem. `ivar` uses Git
worktrees underneath, then adds the multi-repository parts:
- one committed Hall definition that teammates can clone and `ivar sync`;
- a shared feature branch across the repositories you promote;
- read-only guards for repositories outside the feature's write scope;
- per-repository setup scripts for untracked runtime state; and
- a session view with provider configuration, plans, and durable run receipts.
Read the detailed, candid comparison: [Why not just `git worktree`?](docs/why-not-worktree.md).
## Install
```sh
curl -fsSL https://ivar.run/install | sh
```
The installer defaults to zero telemetry, and the installed `ivar` binary never
sends analytics. Its only unrequested request is the update check: at most once
per 20 hours it asks GitHub for the latest release tag, sending nothing but a
`User-Agent` (turn it off with `IVAR_NO_UPDATE_CHECK=1`). To optionally help
count successful installations:
```sh
curl -fsSL https://ivar.run/install | IVAR_INSTALL_ANALYTICS=1 sh
```
Prefer to build from source?
```sh
cargo install ivar
```
Or download a platform binary from the [latest release](https://github.com/mnzsss/ivar/releases/latest).
Each release includes `ivar-linux-x86_64`, `ivar-linux-aarch64`,
`ivar-darwin-x86_64`, and `ivar-darwin-aarch64`, plus a `.sha256` file for every
artifact. The same binaries also come compressed as `.xz` and `.gz`
(`ivar-linux-x86_64.xz` is about a quarter of the size); the install script
uses them when `xz` or `gzip` is available. Decompress with
`xz -d ivar-linux-x86_64.xz` or `gzip -d ivar-linux-x86_64.gz`, then make the
binary executable and put it on your `PATH`.
## Start with a Hall
If a teammate already has a Hall:
```sh
git clone && cd
ivar sync
```
If you are creating one:
```sh
mkdir acme && cd acme
git init
ivar init --name acme
ivar repo add api https://github.com/acme/api
ivar repo add web https://github.com/acme/web
```
Then follow the day-to-day loop: create a feature, promote the repositories it
may change, and start a session. The [getting-started guide](docs/getting-started.md)
walks through both paths.
## Local by architecture
**`ivar` is local-only: there is no ivar server, no account, and no analytics in
the binary.** It keeps no daemon of its own. It arranges
local directories, worktrees, and provider configuration, and keeps a local
SQLite code graph of your repositories that never leaves the machine. `ivar agent` runs the agents
you define inside Docker containers, or on the host under Landlock with
`runtime: host`, fired by systemd user timers.
The binary makes network requests in these cases, none of them to an ivar server:
- the update check described above;
- `git` and `gh`, with your own credentials, to clone repositories and open pull requests;
- OAuth with the MCP servers your hall declares (`ivar mcp auth`);
- the GitHub API, to fetch external skills;
- scheduled agents: it pulls the ivar agent images from GHCR, lets an agent
reach the domains it lists, and POSTs to an agent's `notify` URL, or to
`api.telegram.org` for `notify: telegram:`; a
`runtime: host` agent uses the network its tool uses, unfiltered, and can
read anything your user can, SSH keys included.
`ivar upgrade` updates `ivar` through whichever channel installed it. Read
[Concepts](docs/concepts.md) and [Limitations](docs/reference/limitations.md)
for the exact boundaries.
## Session memory
`ivar` records what happens in each session into `.ivar/memory.db`, on this machine
only: `session.started`, `session.prompted`, `session.tool` and `session.ended`, with
secrets redacted before anything reaches disk. Capture is on by default. To turn it
off, set `"memory": {"capture": false}` in `ivar.json` and run `ivar sync`.
A provider records only the events its hooks expose. OpenCode has no session end,
and T3 records its session end when a thread is closed (archived), not when a turn
finishes. The binary also records delivery events (push, pull request, rebase, integrate,
merge, cleanup, close, delete) into the same database. Session events are deleted 30 days
after the session's last observation; delivery events are kept. See the
[limitations of session capture](docs/reference/limitations-memory.md).
`ivar memory query ` searches the markdown pages under `docs/memory/` (`product`,
`update`, `decision`, `gotcha`, `procedure`, `concept`), with `--kind`, `--tier` and
`--tag` filters. The index follows the files on disk, committed or not, and
`ivar memory reindex` rebuilds it. See the [page format](docs/reference/on-disk-format-pages.md).
Each provider conversation also gets an uncommitted `session` page under
`.ivar/memory/session/`, written from its observations once it ends or goes idle, and
deleted 30 days later.
`ivar memory lint` checks the pages on disk against the page rules and exits non-zero on an
error.
The same server that serves the code graph serves the memory to your agent. It lists
`memory_query` and `memory_write_page` beside sixteen more memory tools, which read, patch,
delete, lint and review pages, read captured observations, and hand work between sessions.
`ivar feature deliver`
requires the review (`memory_review`) before it applies. The tools never commit. See the
[MCP tools](docs/reference/mcp-tools.md).
Pages cite code as anchors: `memory_query` lists them, and `graph_explore` names the pages anchored to what it returns.
A session can leave a handoff for the next one: a summary, pending tasks, open decisions
and changed files. `ivar memory handoff` opens, lists and cancels them from a terminal. On
Claude Code, T3 and OMP, `ivar memory brief` shows the open handoffs when a session starts.
Handoffs expire after `memory.handoff_ttl_days` (7 by default).
## MCP server
`ivar graph mcp` serves the hall's code graph and memory to your harness over MCP as the
`-ivar` server, with `graph_explore`, `graph_feedback` and the eighteen `memory_*` tools.
It runs inside an ivar hall; start it with `ivar graph mcp` from the hall root.
mcp-name: io.github.mnzsss/ivar
## Support
**macOS and Linux.** Windows is not supported because a view dir is built from
symlinks. WSL is untested.
Supported agent harness providers: **Claude Code**, **OpenCode**, and **OMP** (Oh My Pi).
The `t3` provider opens a session in T3 Code and runs Claude Code there, so it requires `claude-code`.
## Documentation
- [Concepts](docs/concepts.md) — Hall, Feature, Promotion, Session, and View Dir.
- [Getting started](docs/getting-started.md) — join or create a Hall.
- [Day to day](docs/guides/day-to-day.md) — feature → promote → session → deliver.
- [Planning and execution](docs/guides/planning-and-execution.md) — SPDD and Run Receipts.
- [Command reference](docs/reference/commands.md) — the complete CLI surface.
- [Documentation index](docs/README.md) — everything else.
The hosted documentation is at .
## Contributing
Please open an issue before a pull request — see [CONTRIBUTING.md](CONTRIBUTING.md).
Commits must be signed off under the [DCO](https://developercertificate.org/):
`git commit -s`.
## License
Apache License, Version 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
The licence covers the code, not the name or the marks: see
[TRADEMARK.md](TRADEMARK.md), which lists what needs no permission.
Unless you explicitly state otherwise, any contribution you intentionally submit
for inclusion in this work shall be licensed as above, without any additional
terms or conditions.
---
single Rust binary · no runtime · no account · no ivar server