References

TL;DR

The top-level references key in opencode.json mounts resources from outside the current project and gives them an alias: use path for local directories (relative, absolute, or ~/) and repository for Git repos (Git URL, host/path, or GitHub owner/repo shorthand, optional branch). Add a description so the agent knows when each reference applies; set "hidden": true to remove it from the TUI’s @ autocomplete while it still feeds context. Attach one with @alias, browse with @alias/. Referenced paths automatically cross the external-directory permission boundary; normal tool permissions still apply.

References give OpenCode access to directories outside the current project. Each reference gets an alias you can use to attach its contents to the conversation.

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use when answering questions about product features"
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use when implementing code against the SDK"
    }
  }
}

Local directories

Use the path field to reference a local directory. Relative paths resolve against the project root, absolute paths are used as-is, and paths starting with ~/ resolve to your home directory:

{
  "references": {
    "shared": { "path": "~/projects/shared-libs" }
  }
}

When no extra options are needed, a plain string is shorthand for path:

{
  "references": {
    "shared": "~/projects/shared-libs"
  }
}

Git repositories

Use the repository field to reference a Git repository. Full Git URLs, host/path values, and GitHub owner/repo shorthand all work. Repositories are cloned to a cache that refreshes asynchronously so references stay up to date:

{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main"
    }
  }
}

The branch field selects a branch or ref; omit it to use the default branch. As with local directories, a string value is shorthand when no branch is needed.

Describe usage

Add a description to tell the agent what each reference is for and when to consult it. References without a description are not surfaced proactively to the agent:

{
  "references": {
    "design-system": {
      "path": "../design-tokens",
      "description": "Use when implementing UI components or design tokens"
    }
  }
}

Hide autocomplete entries

Set "hidden": true to keep a reference out of the TUI’s @ autocomplete menu. Hidden references with a description still participate in the agent’s context:

{
  "references": {
    "archive": {
      "path": "../legacy-archive",
      "description": "Historical context for migration work",
      "hidden": true
    }
  }
}

Use references

In the TUI, type @ followed by an alias to attach a reference’s contents to your message, or @alias/ to fuzzy-search the files inside it. See keybinds for the related shortcuts.

Referenced directories automatically cross the external-directory permission boundary described in permissions, so tools can read them without extra approval. Normal tool-level permission rules continue to apply.

Configure fields

Field	Local	Git	Description
path	✓		Local directory to reference
repository		✓	Git URL, host/path, or owner/repo
branch		✓	Optional branch or ref; defaults to the default branch
description	✓	✓	Guidance for the agent on when to use this reference
hidden	✓	✓	Exclude from the TUI @ autocomplete

Reference aliases cannot be empty or contain /, whitespace, backticks, or commas.