@astrofoundry/pi-astro

Personal customizations for the pi coding agent — registers an astro_agent tool, a grimoire docs tool, a caveman compressed-output toggle, an astro-footer status bar, 8 curated subagents, 4 skills, and an astro theme.

Full setup

1. Install pi

npm install -g @mariozechner/pi-coding-agent

2. Install this package

pi install npm:@astrofoundry/pi-astro

3. Install CLI prerequisites

# grimoire (required by the `grimoire` tool — docs lookup)
npm install -g @astrofoundry/grimoire

# Playwright CLI (required by the `playwright-cli` skill / tester-ui agent)
npm install -g @playwright/cli@latest

# Postman CLI (required by the `postman-cli` skill / tester-api agent)
npm install -g postman-cli

Optional: Raycast app, required only if you use the raycast-script-creator skill.

4. Activate the astro theme

Add to ~/.pi/agent/settings.json:

{ "theme": "astro" }

Or run /settings inside pi and select astro.

5. Verify

pi list           # package shows installed
pi                # launch; confirm [Extensions] lists astro-agents, grimoire, astro-footer

What's inside

Tools (LLM-callable):

• astro_agent — delegate a task to a named subagent in an isolated pi subprocess
• grimoire — search indexed technical documentation via the grimoire CLI
• edit — replaces pi's built-in with batch multi-file edits + Codex-style patch mode, preflight validation, atomic rollback
• gemini_image — generate or edit images via Google Gemini native models + Imagen 4; cost-estimated confirmation before every call

Extensions:

• astro-agents — registers astro_agent + ships 8 bundled subagents
• grimoire — registers grimoire tool
• multi-edit — registers the enhanced edit tool
• gemini-image — registers gemini_image tool (requires a Gemini API key; prompts and saves on first use)
• security-guard — blocks/prompts destructive bash commands and sensitive file access; configure at ~/.pi/agent/security-guard.json (example written on first run); /security-guard status|reload|test
• notify-on-stop — runs a shell command when the agent finishes a turn (sound, voice, desktop notification). Default: off. Enable with /notify on (state persists in ~/.pi/agent/notify-on-stop.json); disable with /notify off. macOS default command: plays the Glass system sound and speaks "Agent done" via say using the Samantha (Enhanced) voice. Linux default: notify-send "pi" "Agent done". Override the voice with PI_STOP_NOTIFY_VOICE=<voice-name> (macOS only; e.g. Alex, Karen, Daniel (Enhanced)). Replace the full command with PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'. Hard-kill (overrides /notify on) with PI_STOP_NOTIFY_OFF=1. Commands: /notify [on|off|status|test]. See extensions/notify-on-stop/README.md for full details.
  • macOS voice install (required once for the default): open System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…, expand English, check Samantha (Enhanced), click Done to download (~500 MB – 1 GB). Verify with say -v "Samantha (Enhanced)" hi. If the voice is missing, say errors silently and you'll only hear the Glass sound.
• vscode-image — only active inside VS Code's integrated terminal (TERM_PROGRAM=vscode). Switches pi-tui's image output to the Kitty graphics protocol so images returned by tools like gemini_image render as real pixels instead of the [Image: …] text fallback. Requires enabling Terminal › Integrated: Enable Images in VS Code settings (off by default); restart the integrated terminal after flipping it. Disable with PI_VSCODE_IMAGE_OFF=1. /vscode-image prints current status.
• astro-footer — two-line powerline-style footer (row 2 only when there's info to show). Row 1: pi · pretty-printed model · thinking · path · git branch + ± counts · tokens (in/out split) · cost (or (sub) for OAuth-authed plans) · context %/total + auto-compact AC. Row 2: subagent count · session time · session name · cache read/write · extension statuses. Auto-detects Nerd Fonts (iTerm/WezTerm/Kitty/Ghostty/Alacritty) with ASCII fallback. Env overrides: ASTRO_FOOTER_NERD_FONTS=0|1, ASTRO_FOOTER_PATH=basename|abbreviated|full. Toggle with /footer [on|off|status]. See extensions/astro-footer/README.md.
• astro-snake — /snake launches an in-pi Snake game (Astro-themed, theme-aware colours, speed ramp, no persistence). See extensions/astro-snake/README.md.
• astro-welcome — pixel-art astronaut welcome screen (24-bit colour, twinkling starfield, rotating funny tagline, live stats) rendered on session start; auto-dismisses after 6 s, on first keystroke, or on first prompt submit. See extensions/astro-welcome/README.md.
• caveman — /caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status] toggles a persistent compressed-output mode. No argument toggles between off and the default level (full). Active level is shown as a footer badge and survives /reload. The skill body at skills/caveman/SKILL.md is also available as a one-shot via /skill:caveman.

Bundled subagents (callable via astro_agent):

• code-reviewer, google-tech-lead, spec-writer, tester-api, tester-ui, ui-architect, ui-design-system, ui-frontend-developer

Skills (loadable via /skill:<name>):

• playwright-cli, postman-cli, raycast-script-creator, caveman

Theme:

• astro — dark, gold accent, GitHub-dark-inspired

Usage

Delegate to a subagent:

use the code-reviewer agent to review src/routes/products.ts

Search docs:

look up Firestore batched writes in the docs

Invoke a skill explicitly:

/skill:playwright-cli

License

ISC