Pi Extensions & Agent Groups

A collection of custom extensions, specialized agents, prompt templates, and workflows for the pi coding agent.

Note

This repository has been restructured to serve as a multi-group repository. It houses different agent setups, custom tools, and experimental configurations. You can use it not only to install the initial agent configurations but also to develop, update, and manage multiple independent agent groups (such as specialized versions for OpenRouter, multi-model execution, or specific coding tasks).

---

What is Pi?

Pi is an interactive terminal coding agent that supports multiple LLM providers (OpenAI, Anthropic, Google, etc.). It can be extended through:

• Extensions — TypeScript modules that add tools, commands, event hooks, and custom UI
• Skills — Markdown-based capability packages loaded on demand
• Prompt Templates — Reusable prompts invoked via /template-name
• Agents — Markdown-defined agent profiles used by squad/subagent extensions for multi-agent orchestration

---

Directory Structure

This repository is organized into independent Agent Groups and architecture diagrams:

├── agents_arch_diagrams/            # Architecture diagrams (Obsidian Canvas format)
│   ├── subagentsV1_architecture.canvas
│   └── subagents_OpenRouter_multimodel_architecture.canvas
│
├── subagentsV1/                     # V1 Agent Group (Core / Classic setup)
│   ├── extensions/
│   │   ├── files.ts                 # /files command — browse session files
│   │   ├── web-search.ts            # web_search + web_fetch tools
│   │   ├── diff.ts                  # /diff command — git diff viewer
│   │   ├── squad/                   # Classic multi-agent orchestration (squad tool)
│   │   │   ├── index.ts
│   │   │   └── agents.ts
│   │   ├── tps.ts                   # Tokens-per-second stats on each turn
│   │   ├── prompt-url-widget.ts     # Widget for PR/issue URL context
│   │   └── redraws.ts               # /tui command — TUI redraw stats
│   ├── agents/                      # Agent profiles for the squad extension
│   │   ├── scout.md
│   │   ├── planner.md
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   ├── tester.md
│   │   └── reviewer.md
│   ├── prompts/                     # Prompt templates
│   │   ├── feature.md               # /feature — full feature workflow
│   │   ├── fullstack.md             # /fullstack — parallel frontend+backend
│   │   ├── implement-review.md      # /implement-review — implement, review, fix
│   │   ├── review.md                # /review — code review
│   │   ├── test.md                  # /test — write tests
│   │   ├── pr.md                    # /pr — structured PR review
│   │   ├── is.md                    # /is — GitHub issue analysis
│   │   ├── cl.md                    # /cl — changelog audit
│   │   └── wr.md                    # /wr — wrap up task (changelog, commit, push)
│   ├── skills/                      # Skills (on-demand reference for the LLM)
│   │   └── squad-workflows/
│   │       └── SKILL.md             # Squad agent and workflow reference
│   └── install.sh                   # Dynamic deploy script for V1
│
├── subagents_OpenRouter_multimodel/ # Multi-Model / OpenRouter Optimized Group
│   ├── extensions/
│   │   └── subagent/                # Specialized subagent orchestrator (subagent tool)
│   │       ├── index.ts
│   │       └── agents.ts
│   ├── agents/                      # Agent profiles for OpenRouter
│   │   ├── scout.md
│   │   ├── planner.md
│   │   ├── worker.md
│   │   ├── tester.md
│   │   └── reviewer.md
│   └── install.sh                   # Dynamic deploy script for OpenRouter group

---

Developing and Adding New Agent Groups

This repository is designed to be easily extensible. If you want to create a new group of custom agents (e.g., subagents_devops, subagents_data_science, etc.):

1. Create a new directory in the root: subagents_<your_group_name>/.
2. Add your custom TS extensions under extensions/ and markdown agents under agents/.
3. Add a dedicated install.sh inside your directory, modeled after subagentsV1/install.sh, to allow clean global installation.

---

Agent Group Details

1. subagentsV1 (Classic Group)

This group registers the /files, /diff, /tui commands and the squad tool.

• Orchestration Tool: squad
• Workflow Templates: /feature, /fullstack, /implement-review, /review, /test, /pr, /is, /cl, /wr
• Agent Rosters:

  Agent	Default Model / Fallback	Description
  scout	Active Session / Haiku	Codebase recon — finds relevant code and returns structured context
  planner	Active Session / Sonnet	Creates implementation plans from context and requirements
  frontend	Active Session / Sonnet	React, CSS, HTML, responsive design, accessibility
  backend	Active Session / Sonnet	APIs, databases, server logic, authentication
  tester	Active Session / Sonnet	Unit, integration, and e2e tests
  reviewer	Active Session / Sonnet	Code review for quality, security, and performance

Note

The classic V1 agents do not define explicit models in their markdown frontmatter, meaning they default dynamically to the active session model of the parent pi instance.

2. subagents_OpenRouter_multimodel (OpenRouter Optimized)

This group is tailored for OpenRouter multi-model architectures, where each agent uses a dedicated, explicit model defined in its frontmatter to optimize task-specific costs and capabilities.

• Orchestration Tool: subagent
• Agent Rosters:

  Agent	Configured Model	Description
  scout	openrouter/deepseek/deepseek-chat	Codebase recon — finds relevant code and returns compressed context
  planner	openrouter/moonshot/kimi-k2.6	Prepares implementation plans
  worker	openai/gpt-5.2-codex	Implements full stack backend and frontend tasks
  tester	openrouter/google/gemini-3-flash-preview	Authors test configurations and sweeps
  reviewer	google/gemini-2.5-flash	Performs structured code and style review

---

Installation & Configuration

Option 1: Install globally via script (Recommended)

To deploy the subagentsV1 classic group globally:

./subagentsV1/install.sh

This dynamically copies V1 extensions, agents, prompts, and skills to your global ~/.pi/agent/ directory.

To deploy the subagents_OpenRouter_multimodel group globally:

./subagents_OpenRouter_multimodel/install.sh

This dynamically copies the OpenRouter subagent orchestrator and multi-model agent profiles to your global ~/.pi/agent/ directory.

Option 2: Copy to your project local directory

You can copy any agent group's folders into your project's .pi/ directory to have them project-scoped:

# Example: Copying subagentsV1 to your project
cp -r subagentsV1/extensions/ /path/to/your/project/.pi/extensions/
cp -r subagentsV1/agents/ /path/to/your/project/.pi/agents/
cp -r subagentsV1/prompts/ /path/to/your/project/.pi/prompts/

Option 3: Reference via settings.json

Point Pi to this repository's extensions dynamically via your project or global settings.json:

{
  "extensions": [
    "/path/to/this-repo/subagentsV1/extensions/files.ts",
    "/path/to/this-repo/subagentsV1/extensions/web-search.ts",
    "/path/to/this-repo/subagentsV1/extensions/diff.ts",
    "/path/to/this-repo/subagentsV1/extensions/squad",
    "/path/to/this-repo/subagents_OpenRouter_multimodel/extensions/subagent"
  ]
}

Settings file locations:

• Project-local: .pi/settings.json
• Global: ~/.pi/agent/settings.json

---

Requirements

• pi coding agent installed and working.
• web-search.ts (V1) requires one of: TAVILY_API_KEY, BRAVE_API_KEY, or SERP_API_KEY.
• files.ts and diff.ts require VS Code (code CLI) for file opening.
• diff.ts requires git difftool configured for VS Code.
• prompt-url-widget.ts requires the GitHub CLI (gh).
• squad/ and subagent/ require pi to be globally available as a command (they spawn subprocesses).

---

License

MIT