@astrofoundry/pi-astro

Personal customizations for the pi coding agent: 16 curated subagents (8 general-purpose + 8 Flourish-pipeline) orchestrated by the bundled pi-subagents, a grimoire docs tool, a caveman compressed-output toggle, an astro-footer status bar, 5 skills, and an astro theme. pi-subagents ships inside this package (bundledDependencies), so a single pi install brings everything.

Full setup

1. Install pi

npm install -g @earendil-works/pi-coding-agent

If you previously installed the older @mariozechner/pi-coding-agent (now deprecated, same code under the new scope), uninstall it to clear deprecation warnings: npm uninstall -g @mariozechner/pi-coding-agent.

2. Install this package

pi install npm:@astrofoundry/pi-astro

pi-subagents is bundled inside this package. It loads automatically from node_modules/pi-subagents/ and registers the subagent tool. Do not also run pi install npm:pi-subagents separately, that would load a second copy and pi would refuse the duplicate tool registration. The astro-agents-loader extension syncs each agents/*.md into ~/.pi/agent/agents/astro.<name>.md on session start so pi-subagents picks them up.

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.
• Flourish SDK (npm install -g @flourish/sdk), required only if you use the flourish-template-developer or flourish-preview-runner agents. If missing, those two agents will attempt to install it for you and stop with the install command if they cannot.

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           # confirm @astrofoundry/pi-astro is installed
pi                # launch; confirm [Extensions] lists astro-agents-loader, grimoire, astro-footer, subagent, etc.

What's inside

Tools (LLM-callable):

• subagent (from the bundled pi-subagents) - delegate tasks to any of the bundled agents, run them in parallel, chain them, or run them async with status/interrupt/resume
• grimoire - search indexed technical documentation via the grimoire CLI
• edit - replaces pi's built-in with batch multi-file edits and Codex-style patch mode, preflight validation, atomic rollback
• gemini_image - generate or edit images via Google Gemini native models and Imagen 4; cost-estimated confirmation before every call

Extensions:

• astro-agents-loader - copies bundled agent definitions into ~/.pi/agent/agents/astro.<name>.md on session start so pi-subagents discovers them. Idempotent, namespaced, prunes stale entries.
• 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 to 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: session time, session name, cache read/write, any extension status keys. 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 the subagent tool from pi-subagents):

• General-purpose: code-reviewer, google-tech-lead, spec-writer, tester-api, tester-ui, ui-architect, ui-design-system, ui-frontend-developer
• Flourish pipeline: flourish-input-vision (image to spec), flourish-input-narrative (text to spec), flourish-input-codebase (HTML to spec), flourish-architect (spec to plan), flourish-template-developer (plan to SDK template, needs @flourish/sdk), flourish-example-builder (template to realistic example), flourish-preview-runner (multi-breakpoint preview + screenshots, needs @flourish/sdk), flourish-reviewer (audit)

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

• playwright-cli, postman-cli, raycast-script-creator, caveman, flourish-chart-spec

Theme:

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

Usage

Delegate to a subagent:

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

Run several agents in parallel via pi-subagents:

run reviewer and tester-api in parallel on the auth middleware changes

Search docs:

look up Firestore batched writes in the docs

Invoke a skill explicitly:

/skill:playwright-cli

License

ISC