pi-sage

Interactive-only advisory Sage extension for Pi.

Runtime requirements (for users)

• Pi CLI installed (pi) and available on PATH
• Pi version: 0.64.0+ recommended
• Model access configured in Pi (API keys / provider auth)
• OS: Linux/macOS/Windows supported
• Optional: git CLI for git-review-readonly profile

Important: Sage spawns a nested pi subprocess for consultations, so pi must be invokable from the environment where Pi itself is running.

Install

Global install (all projects)

pi install npm:pi-sage

Project-local install (current project only)

pi install -l npm:pi-sage

Then in Pi run:

/reload

Usage

• Ask naturally: “use Sage”, “get a second opinion”, etc.
• Or the model may invoke Sage autonomously when appropriate.
• Configure via:

/sage-settings

Tool profiles

• read-only-lite: ls, glob, grep, read
• git-review-readonly (default): adds restricted bash for allowlisted read-only git commands
• none
• custom-read-only
• yolo: unrestricted available tools/commands (including node/npm/cd/tests). High risk, explicit opt-in only.

Settings files (global + project override)

Sage settings are resolved in this order:

1. .pi/sage-settings.json (project override)
2. ~/.pi/agent/sage-settings.json (global fallback)
3. built-in defaults

So yes: a global install can use global settings, and any project can override with its own .pi/sage-settings.json.

Install scope and file layout

Global install (pi install npm:pi-sage)

Pi writes package source to:

• ~/.pi/agent/settings.json

Package files are installed globally by npm (npm install -g), typically under npm's global prefix, e.g.:

• Windows (typical): %APPDATA%/npm/node_modules/pi-sage/
• macOS/Linux (typical): <npm-global-prefix>/lib/node_modules/pi-sage/

Use npm root -g to see your exact global node_modules path.

Project-local install (pi install -l npm:pi-sage)

Pi writes package source to:

• .pi/settings.json

Package files are installed under project-local Pi package storage:

• .pi/npm/ (project-local package cache/install root)

Settings files (independent of install scope)

• Global Sage settings: ~/.pi/agent/sage-settings.json
• Project Sage settings: .pi/sage-settings.json

Project settings always override global settings for that project.

Publishing note

Package name sage is already taken on npm. pi-sage is currently available and is the intended publish name.

Install troubleshooting

If pi install pi-sage fails with a local-path error (for example Path does not exist: .../pi-sage), your Pi version is interpreting bare names as local paths. Use the explicit npm source form instead:

pi install npm:pi-sage