References

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:

{
  "$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:

{
  "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:

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

Git repositories

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

{
  "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:

{
  "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:

~/.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.

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:

{
  "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:

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

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