pi-file-reference

A pi extension that resolves @filepath references in AGENTS.md and injects the referenced file contents into the system prompt.

How it works

1. On session_start, the extension reads AGENTS.md (project-local first, then ~/.pi/agent/ as fallback)
2. Parses @filepath references from the file
3. Reads the referenced files and caches their contents in session state (survives reload)
4. On before_agent_start, injects the file contents into the system prompt

@filepath syntax

@path/to/file.md
@./path/to/file.md
@~/path/to/file.md
@"path with spaces.md"
@/absolute/path/to/file.md

The @ must be at the start of a line or preceded by whitespace.

Directory references

When @path resolves to a directory, all immediate files (depth 1) are injected:

@./docs

Injects @docs/style-guide.md, @docs/patterns.md, etc. (sorted alphabetically). Subdirectories are skipped. Trailing / is stripped (@./docs/ works the same).

Installation

# Install from npm (once published)
pi install npm:@josephyoung/pi-file-reference

# Or clone and link locally
git clone https://github.com/your-org/pi-file-reference.git
cd pi-file-reference
npm install
pi install .

Usage

In your AGENTS.md:

# Project guidelines
Always follow the patterns in @./docs/style-guide.md

# Architecture
@~/.project-arch/backend-overview.md

The referenced files' content is automatically injected into the system prompt at the start of each agent turn.

License

MIT