pi-references

name	pi-references
description	Manage Pi project references: add, edit, remove, inspect, or debug local directory and Git repository references used as project context.

pi-references

Use this to modify references in Pi settings.

Settings files

Global:

~/.pi/agent/settings.json

Project-local, trusted projects only:

.pi/settings.json

Project-local aliases override global aliases.

Add references

Local directory:

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

Git repository:

{
  "references": {
    "sdk": {
      "repository": "owner/repo",
      "branch": "main",
      "description": "Use for SDK implementation details"
    }
  }
}

String shorthand:

{
  "references": {
    "docs": "../docs",
    "effect": "Effect-TS/effect-smol"
  }
}

Strings starting ., /, or ~ are local paths. Other strings are Git repos.

Fields

• path: local directory.
• repository: Git repo. Supports GitHub owner/repo, Git URLs, host/path refs.
• branch: optional Git branch/ref.
• description: when agent should use the ref. Described refs enter system context.
• hidden: hide from @ autocomplete only.

Alias rules: nonempty; no /, whitespace, backticks, commas.

Path bases

Relative paths resolve from settings base:

• global: ~/.pi/agent
• project-local: <project>/.pi

Git refs clone under:

~/.pi/references/repos/<host>/<owner>/<repo>

After editing settings

After modifying references, tell the user to run:

/references-refresh

This reloads settings and refreshes Git refs. If they only want to view loaded refs, tell them to run:

/references

Debug checklist

• Read relevant settings file first.
• Check project is trusted for .pi/settings.json.
• Check alias validity.
• Check relative path base.
• Check target local dir exists.
• Check Git repo string parses.
• Check branch only uses alnum, /, _, ., -; not leading -; no ...
• Inspect index.ts if actual runtime behavior matters.