opencode/packages/docs/references.mdx

---
title: "References"
description: ""
---

References give OpenCode named access to directories outside the current
project. Use them for documentation, shared libraries, examples, or source from
another repository.

Configure references by alias in `opencode.json` or `opencode.jsonc`:

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and terminology"
    },
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
      "description": "Use for Effect implementation details"
    }
  }
}
```

## Local directories

Use `path` for a local directory:

```jsonc
{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when working with components or design tokens"
    }
  }
}
```

Relative paths resolve from the directory containing the config file that
defines them. Absolute paths and home-relative paths such as `~/docs` are also
supported.

The string shorthand is useful when no other fields are needed:

```jsonc
{
  "references": {
    "docs": "../docs",
    "shared": "~/work/shared"
  }
}
```

<Note>
  A shorthand string is treated as a local path only when it starts with `.`,
  `/`, or `~`. Use `./docs`, not `docs`; a bare `docs` value is interpreted as
  a Git repository.
</Note>

## Git repositories

Use `repository` for a remote Git repository. GitHub `owner/repo` shorthand,
Git URLs, host/path forms, and SCP-style remotes are supported.

```jsonc
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main"
    },
    "internal-sdk": {
      "repository": "git@gitlab.example.com:platform/sdk.git",
      "branch": "release/v2"
    }
  }
}
```

Without `branch`, OpenCode checks out and refreshes the remote's default
branch. Branch names may contain letters, numbers, `/`, `_`, `.`, and `-`, but
cannot start with `-` or contain `..`. Local `file:` repositories are not
supported.

Git references also support shorthand:

```jsonc
{
  "references": {
    "effect": "Effect-TS/effect",
    "sdk": "gitlab.com/platform/sdk"
  }
}
```

### Cloning and storage

OpenCode normalizes a remote and stores one checkout under its global data
directory at `opencode/repos/<host>/<repository-path>`. On a typical Linux
installation, for example, `Effect-TS/effect` is stored at:

```text
~/.local/share/opencode/repos/github.com/Effect-TS/effect
```

Missing repositories are cloned. Existing checkouts are fetched and reset to
the requested branch, or to the remote default branch when `branch` is omitted.
Materialization runs asynchronously when references load or reload, so a new
reference can appear before its checkout is ready. Clone and refresh failures
are logged and do not stop other references from loading.

<Warning>
  The cache has one checkout per normalized remote, not one per branch. Do not
  configure the same repository at multiple branches; only one branch can be
  exposed. Avoid editing cached checkouts because a refresh resets them.
</Warning>

## Description and visibility

`description` tells agents when a reference is relevant. References with a
description are included in agent instructions with their alias and resolved
path. References without one remain available in `@` autocomplete but are not
advertised automatically.

Set `hidden` to `true` to remove a reference from TUI `@` autocomplete:

```jsonc
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal service behavior",
      "hidden": true
    }
  }
}
```

`hidden` controls only autocomplete visibility. It does not remove the
reference from the reference API or agent instructions when a description is
present.

## Use references

Type `@` in the TUI and select a reference alias to attach its root directory:

```text
Compare the current implementation with @effect
```

The attachment provides a non-recursive listing of the root's immediate files
and directories. V2 currently attaches references by root alias;
`@alias/path` is not a reference-specific file browser. Ask the agent to
inspect a particular path when more detail is needed.

References do not grant extra tool permissions. Access outside the active
Location remains subject to the agent's normal tool rules and the
`external_directory` permission. Editing a reference additionally requires the
applicable edit permission.

## Fields

| Field | Local | Git | Description |
| --- | --- | --- | --- |
| `path` | Required | No | Local directory path |
| `repository` | No | Required | Remote Git repository |
| `branch` | No | Optional | Branch to fetch and check out |
| `description` | Optional | Optional | Guidance describing when agents should use it |
| `hidden` | Optional | Optional | Hide it from TUI `@` autocomplete |

An alias cannot be empty or contain `/`, `\`, whitespace, a backtick, or a
comma.