pi-agents-local

Pi extension that loads AGENTS.local.md and/or CLAUDE.local.md from the current working directory and appends them to the effective system prompt as private project instructions.

Use this for machine-local or personal project instructions that should not be committed to the repository.

Requirements

• Pi installed and available as pi
• Node/npm available for npm-based installation

Install

Install the published npm package globally:

pi install npm:pi-agents-local

Install a pinned version for reproducible setup:

pi install npm:pi-agents-local@0.1.0

Install from GitHub instead of npm:

pi install git:github.com/danieldisu/pi-agents-local@v0.1.0

Install project-locally so the dependency is recorded in .pi/settings.json and shared with teammates:

pi install -l npm:pi-agents-local@0.1.0
# or
pi install -l git:github.com/danieldisu/pi-agents-local@v0.1.0

Try from a local checkout without installing:

pi -e .

Install from a local checkout:

pi install .

Usage

Create AGENTS.local.md or CLAUDE.local.md in the directory where you start Pi:

cat > AGENTS.local.md <<'EOF'
Private local instructions go here.
EOF

cat > CLAUDE.local.md <<'EOF'
Private Claude-style local instructions go here.
EOF

If both files exist, both are loaded. AGENTS.local.md is injected first, followed by CLAUDE.local.md.

Keep them uncommitted. For a single repository, prefer .git/info/exclude:

echo "AGENTS.local.md" >> .git/info/exclude
echo "CLAUDE.local.md" >> .git/info/exclude

Or add them to .gitignore if the whole team should avoid committing local instruction files:

echo "AGENTS.local.md" >> .gitignore
echo "CLAUDE.local.md" >> .gitignore

The extension reads the files on each agent start, so edits are picked up without caching.

Command

Inside Pi:

/agents-local-status

Shows whether AGENTS.local.md and CLAUDE.local.md exist, their paths, byte sizes, modification times, and injection status.

Guardrails

• Only reads AGENTS.local.md and CLAUDE.local.md from ctx.cwd
• Does not traverse parent directories
• Does not accept arbitrary paths
• Does not log or display file contents
• Skips files larger than 50KB
• Skips unreadable files and notifies once when UI is available

Security Notes

Pi extensions run with your local user permissions. Only install packages from sources you trust, and review local instruction file contents before starting Pi in sensitive projects.

AGENTS.local.md and CLAUDE.local.md are intended for private local instructions. Do not put secrets, API keys, passwords, or tokens in them.

Updating and Removing

Update non-pinned installs:

pi update npm:pi-agents-local

Remove the package:

pi remove npm:pi-agents-local

If you installed a pinned version, install a newer pinned version explicitly:

pi install npm:pi-agents-local@0.1.1

Development

Run tests:

npm test

Validate package contents before publishing:

npm pack --dry-run