# Use OpenCode with multiple repositories
> OpenCode reaches other repos through references; ivar adds one feature branch, one plan and one pull request per repo across them.
Source: https://ivar.run/docs/with/opencode

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](/docs/reference/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](https://opencode.ai/docs/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

```sh
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](/docs/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.

```sh
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:

```sh
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](/docs/providers/opencode).

## 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](/docs/guide/mcp/providers/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](/docs/reference/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.