Use OpenCode with multiple repositories

OpenCode can read directories and Git repositories outside the project through references. ivar adds what references leave open: a feature branch across the repos, a write scope that is guarded (kernel-enforced on Linux; see Limitations) on the repos you have not promoted, one plan, and one pull request per repo.

What OpenCode does on its own

As of 2026-10-06, OpenCode documents references in opencode.json. A reference is a local path or a Git repository with an optional branch. Git references live in a local cache and follow the default branch when you give none. References pass through OpenCode's external-directory permission boundary, and normal tool permissions still apply: an agent that cannot edit files does not gain edit access because a directory is a reference (OpenCode references, accessed 2026-10-06).

Whether OpenCode blocks writes into a reference is not documented on that page. Worktrees, a branch shared across repos and a pull request flow are not documented either.

Install and create a hall

curl -fsSL https://ivar.run/install | sh
ivar init --provider opencode

In an existing hall, ivar provider add opencode registers the provider. Add each repo with ivar repo add <name> <url>. The quickstart walks through it.

One change across repos

The example hall has api, web, shared-types and infra. The request: add an avatarUrl field to the user profile, return it from the API and render it on the web profile page.

ivar feature create avatar-url
ivar feature promote avatar-url api
ivar feature promote avatar-url web
ivar feature promote avatar-url shared-types
ivar session start avatar-url --provider opencode

Inside the session, run /ivar-plan and approve each gate. Then, from the hall:

ivar feature deliver avatar-url --preview

The preview lists three pull requests: api, web and shared-types. infra stays guarded and gets none.

What lands in the session

An OpenCode session gets AGENTS.md, the hall's skills, the /ivar-* commands in .opencode/ and an opencode.json whose mcp key ivar owns. The write guard is a plugin in .opencode/plugins/. See the OpenCode provider.

MCP servers

Declare each server once in ivar.json. ivar sync rewrites the mcp key of opencode.json, and ivar mcp auth handles OAuth. See MCP for OpenCode.

Limits

• ivar runs on Linux and macOS. Windows is not supported.
• references grant access to a directory under OpenCode's own permissions. The write scope of an ivar session comes from what you promoted, not from references.
• On Linux, a write to an unpromoted repo fails with EACCES from the kernel. On macOS only the worktree root loses its write bit. See Limitations.

FAQ

Are OpenCode references read-only?

Not documented. The page says normal tool permissions still apply. If you need unpromoted repos guarded, ivar does it for the session.

Does OpenCode create one branch across several repos?

Not documented. ivar feature create names the branch once, and ivar feature promote puts a worktree on it in each repo you name.

Can I move this feature to another harness?

Yes. ivar session relay avatar-url --provider claude-code opens the same feature in Claude Code.