@astrofoundry/pi-astro

Personal customizations for the pi coding agent: 19 subagents (8 general-purpose, 8 Flourish-pipeline, 3 homelab specialists) run by the bundled astro-subagents extension, a grimoire docs tool, a caveman compressed-output toggle, an astro-footer status bar, 8 skills, and an astro theme.

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

Agents load straight from the package: bundled agents are named astro.<name> (for example astro.code-reviewer), your own agents in ~/.pi/agent/agents/*.md keep their plain names. If an earlier version copied bundled agents into that folder as astro.*.md, the first session removes those copies.

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-subagents, grimoire, astro-footer, specialist-gate, etc.

What's inside

Tools (LLM-callable):

• subagent - delegate a task to any agent, run several in parallel, or chain them ({previous} carries the prior output). Each agent runs in its own pi process with its own tool allowlist and skills; /run <agent> -- <task> does the same from the prompt, /agents lists what is available
• 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-subagents - the subagent tool, /run, and /agents. Reads agents/*.md from this package and ~/.pi/agent/agents; a child may delegate one more level by default (maxSubagentDepth in an agent tightens it)
• 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
• specialist-gate - gives each specialist agent (astro.arcane, astro.identity, astro.network) its single tool, which runs the matching CLI wrapper as a dedicated macOS user through sudo, and blocks every other agent from calling those CLIs or reading their credentials. Inactive until the host has ~/.pi/agent/specialists.json. /specialists prints the status. Host setup is described in specialists/README.md.
• 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 (call them as astro.<name>):

• General-purpose: code-reviewer, google-tech-lead, spec-writer, tester-api, tester-ui, ui-architect, ui-design-system, ui-frontend-developer
• Specialists (one homelab area each, need the host setup in specialists/README.md): arcane (Arcane container platform, GitOps first), identity (Zitadel, Pomerium, certificates), network (UniFi, FreeRADIUS, Tailscale, read-only)
• 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, arcane, identity, network (the last three are injected into their specialist agents)

Theme:

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

Usage

Delegate to a subagent:

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

Run several agents in parallel:

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

Or from the prompt line:

/run astro.arcane -- list the Arcane projects and their state

Search docs:

look up Firestore batched writes in the docs

Invoke a skill explicitly:

/skill:playwright-cli

License

ISC