Pi Agent

Personal configuration and extensions for the Pi coding agent.

Included extensions

• ask-user — lets an agent ask a multiple-choice question in the TUI.
• background-terminals — runs and manages long-lived shell commands.
• codex-profiles — provides isolated Personal and Work Codex profiles with separate authentication and rate-limit status.
• firecrawl-search — adds web search, scrape, and crawl tools through Firecrawl.
• file-search — adds fd file discovery and rg content-search tools.
• rtk — rewrites supported shell commands through rtk to reduce output tokens.
• subagents — starts background Pi, Claude, or Codex subagents.
• workflows — orchestrates isolated Pi agents through model-authored, multi-phase JavaScript workflows, with parallel execution, structured outputs, background runs, persisted artifacts, and a /workflows dashboard.
• summaries — manages conversation summaries.
• git-info and ui-customization — show branch/change information and provide /lg, an interactive local-diff browser.
• model-info — supplies live model, context, cost, and generation-rate data to the customized footer.

Setup

Use this repository as Pi's agent directory (normally ~/.pi/agent). It requires Bun 1.3.14 or later.

Install the root and extension dependencies:

bun install
bun run install:extensions

To enable the Firecrawl extension, copy .env.example to .env and set a valid FIRECRAWL_API_KEY.

The workflow extension requires a Node runtime that supports permission mode (--permission); Node 24 is recommended. Its acorn dependency is installed by the root bun install command.

Workflows

Ask the agent explicitly to run a workflow, or use the ultracode trigger:

ultracode: review the authentication system using parallel agents

Workflow scripts can organize work into phases, fan tasks out to as many as four agents concurrently, request schema-validated structured results, and run in either blocking or background mode. Use /workflows to inspect runs, phases, individual agent transcripts, usage, and results.

Run artifacts are stored under ~/.pi/agent/workflows/<runId>/. Background runs last only for the current Pi session and are aborted during reload, session replacement, or shutdown.

Development

bun run check
bun run test
bun run format:check

Run bun run format to apply formatting.