pi-extra-context

Load extra configured context files into pi sessions.

pi-extra-context is a small extension for adding project, ancestor, global, or absolute Markdown/text files to the system prompt alongside Pi's built-in AGENTS.md / CLAUDE.md context.

Install

pi install npm:@alasano/pi-extra-context

Configuration

Create one or both config files:

Path	Scope
~/.pi/agent/extensions/pi-extra-context.json	Global
.pi/pi-extra-context.json	Project-local

Global and project configs are merged. File entries are appended in this order:

1. global config files
2. project config files

Project config values override global values for limits like maxBytesPerFile and maxTotalBytes.

Example: load CLAUDE.local.md

{
  "files": [
    {
      "path": "CLAUDE.local.md",
      "mode": "ancestor",
      "optional": true
    }
  ]
}

With mode: "ancestor", the extension walks from the filesystem root to the current working directory and loads matching files parent-first. This mirrors Pi's built-in parent-directory context behavior, but for files you choose.

Example: load project rules and global notes

{
  "files": [
    {
      "path": ".cursor/rules/*.md",
      "mode": "project",
      "optional": true
    },
    {
      "path": "local-context/**/*.md",
      "mode": "global",
      "optional": true
    },
    {
      "path": "~/Notes/pi/**/*.md",
      "mode": "absolute",
      "optional": true
    }
  ],
  "maxBytesPerFile": 50000,
  "maxTotalBytes": 200000
}

File entries

Each file entry supports:

Field	Type	Default	Description
path	string	required	File path or glob pattern
mode	string	"project"	How to resolve path
optional	boolean	true	Whether missing matches should be silent

String shorthand is also supported:

{
  "files": ["docs/project-context.md"]
}

String entries are treated as project-relative and optional.

Modes

Mode	Resolution behavior
project	Resolve path relative to the current Pi working dir
ancestor	Apply path at every ancestor from root to current dir
global	Resolve path relative to ~/.pi/agent
absolute	Resolve path as an absolute or ~-prefixed path

Paths may use Node's built-in glob syntax. This package requires Node >=22.17.0, where fsPromises.glob() is stable.

Limits

Defaults:

{
  "maxBytesPerFile": 50000,
  "maxTotalBytes": 200000
}

Files exceeding maxBytesPerFile are skipped. Files that would exceed maxTotalBytes are also skipped. Skipped files appear in /pi-extra-context status.

Commands

Command	Description
/pi-extra-context	Show current status
/pi-extra-context status	Show loaded files, limits, and warnings
/pi-extra-context reload	Reread config and context files

Pi also reloads the extension on /reload, so config and files are reread then as well.

How it works

On session start and /reload, the extension:

1. reads global and project config
2. resolves configured files and glob patterns
3. deduplicates files by real path
4. enforces byte limits
5. caches file contents in memory

Before each agent turn, it appends the cached contents to the system prompt. It does not reread files every turn and does not append messages to the conversation transcript.

Limitations

Pi's extension API does not currently allow extensions to contribute native context files through resources_discover. As a result, pi-extra-context appends cached content to the system prompt rather than registering files in Pi's native AGENTS.md / CLAUDE.md context-file list.