pi-references

Opencode-style project references for Pi. (yes, this is a slop fork)

pi-references lets you name directories outside the current project and use them from Pi with @alias/ paths. Use it for product docs, shared libraries, SDK source, examples, design systems, or another repository you want the agent to inspect while working.

References can point to:

• local directories (../docs, ~/code/design-system, /opt/shared)
• Git repositories (owner/repo, Git URLs, host/path references)

When configured, the extension:

• adds described references to Pi's system prompt so the agent knows when to use them
• packages a compact (<100 LOC) pi-references skill for configuration/debugging guidance
• adds @alias/ autocomplete in the TUI
• lets prompts use @alias/path and rewrites them to the resolved absolute path
• rewrites tool-call paths for read, ls, find, grep, edit, and write
• clones/refreshes Git references asynchronously under ~/.pi/references/repos/...

Install

From npm:

pi install npm:pi-references

From GitHub:

pi install git:github.com/jeremyosih/pi-references

Or try without installing:

pi -e git:github.com/jeremyosih/pi-references

If Pi is already running after installation, reload resources:

/reload

Try

In Pi:

Add Effect-Ts/effect-smol to this project references.

Configure references

Add references to Pi settings.

Global settings:

~/.pi/agent/settings.json

Project-local settings:

.pi/settings.json

Project-local settings are loaded only after Pi trusts the project. If global and project settings define the same alias, the project reference wins.

{
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions"
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details"
    }
  }
}

Local directories

Use path to reference a local directory.

{
  "references": {
    "docs": {
      "path": "../docs",
      "description": "Use for product docs"
    }
  }
}

Paths can be:

• relative to the settings file base directory
  • global: relative to ~/.pi/agent
  • project-local: relative to <project>/.pi
• absolute, like /home/user/docs
• home-relative, like ~/docs

String shorthand works too. Strings that start with ., /, or ~ are treated as local paths:

{
  "references": {
    "docs": "../docs"
  }
}

Git repositories

Use repository to reference a Git repo. The extension clones or refreshes it in Pi's reference cache and exposes the checked-out source as a normal reference directory.

{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect-smol",
      "branch": "main",
      "description": "Use for Effect v4 implementation details"
    }
  }
}

repository accepts GitHub owner/repo shorthand, Git URLs, and host/path references. branch is optional. Without it, Git uses the repository default/upstream branch.

String shorthand works when you do not need branch, description, or hidden:

{
  "references": {
    "effect": "Effect-TS/effect-smol"
  }
}

Git references refresh asynchronously. A newly configured repo may take a moment to finish cloning before file autocomplete can list its contents.

Describe usage

Add description to tell the agent when to use a reference.

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

References with descriptions are injected into Pi's system prompt. References without descriptions still work through @alias/ autocomplete and direct use, but are not advertised to the agent proactively.

Hide autocomplete entries

Set hidden to true to omit a reference from TUI @ autocomplete.

{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true
    }
  }
}

hidden only affects autocomplete. A hidden reference with a description is still included in agent guidance.

Use references

Configured references appear in TUI @ autocomplete. Type @alias/ to search files inside a reference.

Compare this implementation with @sdk/src/client.ts

The extension rewrites @sdk/src/client.ts to the resolved absolute path before the model/tool layer uses it.

You can also ask the agent to inspect a described reference without attaching it manually, because described references are included in system context.

Fields

| Field | Local | Git | Description | | --- | --- | --- | --- | | path | Yes | No | Local reference directory | | repository | No | Yes | Git URL, host/path, or GitHub owner/repo value | | branch | No | Yes | Optional Git branch or ref | | description | Yes | Yes | Guidance describing when to use the reference | | hidden | Yes | Yes | Hide the reference from TUI @ autocomplete |

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

Skill

The extension contributes a bundled skill:

/skill:pi-references

Use it when configuring, editing, debugging, or documenting references.

Commands

/references

Reload settings and show configured references.

/references-refresh

Clear clone in-flight state, reload settings, and refresh Git references.