@astrofoundry/pi-astro

Personal customizations for the pi coding agent: 25 subagents (8 general-purpose, 8 Flourish-pipeline, 9 homelab specialists) run by the bundled astro-subagents extension, a grimoire docs tool, a caveman compressed-output toggle, an astro-footer status bar, 14 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 and saves the agent's session, /run <agent> --continue -- <task> resumes it, /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
• astro-discord - Discord access to the specialists: in the configured channels, <specialist> <task> runs astro.<specialist> and posts the answer as a reply (⏳ running, 🔒 waiting for an owner's approval of a risky call, ✅ done, ❌ failed). Owners may use every specialist and approve risky calls with buttons; other users only the specialists listed for them; everyone else is ignored. Inert unless the headless host sets ASTRO_DISCORD=1; setup with d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts" (Node refuses to strip types inside node_modules, hence the copy), which prompts for the bot token and ids, checks them against Discord, and writes the LaunchAgent. See specialists/README.md.
• specialist-gate - gives each specialist agent (astro.arcane, astro.identity, astro.network, astro.dns, astro.edge, astro.security, astro.backup, astro.proxmox, astro.inference) 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 routes through the homelab repository, certificates), network (UniFi reads and firewall policies, FreeRADIUS, Tailscale), dns (Technitium resolvers, Cloudflare zones), edge (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository), security (Wazuh, CrowdSec, log archive, read-only), backup (vzdump, Restic layers, GCS offsite, restore tests), proxmox (guest lifecycle, snapshots, resources; no create or destroy), inference (llama.cpp on Nexus, Hermes gateways and upgrades, Europa health)
• 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, dns, edge, security, backup, proxmox, inference (the last nine 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