@mariozechner/pi-coding-agent@mariozechner/pi-coding-agent@mariozechner/pi-coding-agent
Coding agent CLI with read, bash, edit, write tools and session managementCoding agent CLI with read, bash, edit, write tools and session managementCoding agent CLI with read, bash, edit, write tools and session management
Version 0.70.6 published 2026-04-28 by badlogic
Maintainers: badlogic mitsuhiko
Keywords: coding-agent ai llm cli tui agent
https://npm.im/@mariozechner/pi-coding-agent

@oh-my-pi/pi-coding-agent@oh-my-pi/pi-coding-agent@oh-my-pi/pi-coding-agent
Coding agent CLI with read, bash, edit, write tools and session managementCoding agent CLI with read, bash, edit, write tools and session managementCoding agent CLI with read, bash, edit, write tools and session management
Version 14.5.6 published 2026-04-29 by can1357
Maintainers: can1357
Keywords: coding-agent ai llm cli tui agent
https://npm.im/@oh-my-pi/pi-coding-agent

@mariozechner/pi-agent-core@mariozechner/pi-agent-core@mariozechner/pi-agent-core
General-purpose agent with transport abstraction, state management, and attachment supportGeneral-purpose agent with transport abstraction, state management, and attachment supportGeneral-purpose agent with transport abstraction, state management, and attachment support
Version 0.70.6 published 2026-04-28 by badlogic
Maintainers: badlogic mitsuhiko
Keywords: ai agent llm transport state-management
https://npm.im/@mariozechner/pi-agent-core

@plannotator/pi-extension@plannotator/pi-extension@plannotator/pi-extension
Plannotator extension for Pi coding agent - interactive plan review with visual annotationPlannotator extension for Pi coding agent - interactive plan review with visual annotationPlannotator extension for Pi coding agent - interactive plan review with visual annotation
Version 0.19.3 published 2026-04-29 by GitHub Actions
Maintainers: backnotprop
Keywords: pi-package plannotator plan-review ai-agent coding-agent
https://npm.im/@plannotator/pi-extension

pi-acppi-acppi-acp
ACP adapter for pi coding agentACP adapter for pi coding agentACP adapter for pi coding agent
Version 0.0.26 published 2026-04-18 by deepstereo
Maintainers: deepstereo
Keywords: acp agent-client-protocol pi-coding-agent adapter
https://npm.im/pi-acp

whatsapp-piwhatsapp-piwhatsapp-pi
WhatsApp integration extension for PiWhatsApp integration extension for PiWhatsApp integration extension for Pi
Version 1.0.43 published 2026-04-29 by castelloes
Maintainers: castelloes
Keywords: pi pi-package pi-extension whatsapp baileys agent
https://npm.im/whatsapp-pi

@agentuity/coder-tui@agentuity/coder-tui@agentuity/coder-tui
Agentuity Coder Hub extension for Pi coding agentAgentuity Coder Hub extension for Pi coding agentAgentuity Coder Hub extension for Pi coding agent
Version 2.0.12 published 2026-04-28 by jhaynie
Maintainers: p0tofpie huijiro jhaynie robindiddams
https://npm.im/@agentuity/coder-tui

@juicesharp/rpiv-pi@juicesharp/rpiv-pi@juicesharp/rpiv-pi
Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validateSkill-based development workflow for Pi Agent — discover, research, design, plan, implement, validateSkill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate
Version 1.0.5 published 2026-04-29 by juicesharp
Maintainers: juicesharp
Keywords: pi-package pi-extension rpiv skills workflow
https://npm.im/@juicesharp/rpiv-pi

@ollama/pi-web-search@ollama/pi-web-search@ollama/pi-web-search
Web search and fetch tools for Pi agent - uses Ollama's web search and fetch APIsWeb search and fetch tools for Pi agent - uses Ollama's web search and fetch APIsWeb search and fetch tools for Pi agent - uses Ollama's web search and fetch APIs
Version 0.0.5 published 2026-03-28 by parthollama
Maintainers: jmorgan mchiang0610 drifkin bruce-ollama parthollama
Keywords: pi-package pi-extension web-search ollama
https://npm.im/@ollama/pi-web-search

@a5c-ai/babysitter-pi@a5c-ai/babysitter-pi@a5c-ai/babysitter-pi
Babysitter package for Pi Coding AgentBabysitter package for Pi Coding AgentBabysitter package for Pi Coding Agent
Version 0.1.3 published 2026-04-04 by tmuskal
Maintainers: tmuskal benihak
Keywords: pi pi-package babysitter orchestration ai-agent
https://npm.im/@a5c-ai/babysitter-pi

@cleocode/cleo-os@cleocode/cleo-os@cleocode/cleo-os
CleoOS — the batteries-included agentic development environment wrapping PiCleoOS — the batteries-included agentic development environment wrapping PiCleoOS — the batteries-included agentic development environment wrapping Pi
Version 2026.4.154 published 2026-04-28 by GitHub Actions
Maintainers: kryptobaseddev
https://npm.im/@cleocode/cleo-os

@heart-of-gold/toolkit@heart-of-gold/toolkit@heart-of-gold/toolkit
Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and moreCross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and moreCross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more
Version 0.1.50 published 2026-04-26 by ondrejsvec
Maintainers: ondrejsvec
Keywords: codex claude-code opencode pi pi-package ai-agents skills agents-md agentskills harness-engineering heart-of-gold
https://npm.im/@heart-of-gold/toolkit

gsd-pigsd-pigsd-pi
GSD — Get Shit Done coding agentGSD — Get Shit Done coding agentGSD — Get Shit Done coding agent
Version 2.78.1 published 2026-04-25 by glittercowboy
Maintainers: glittercowboy
https://npm.im/gsd-pi

pi-mermaidpi-mermaidpi-mermaid
🧜♀ Pi extension that renders Mermaid diagrams as ASCII in the TUI🧜♀ Pi extension that renders Mermaid diagrams as ASCII in the TUI🧜♀ Pi extension that renders Mermaid diagrams as ASCII in the TUI
Version 0.3.0 published 2026-02-23 by gurpartap
Maintainers: gurpartap
Keywords: pi pi-extension pi-package mermaid ascii tui
https://npm.im/pi-mermaid

my-pimy-pimy-pi
Composable pi coding agent with MCP, LSP, prompt presets, and local eval telemetryComposable pi coding agent with MCP, LSP, prompt presets, and local eval telemetryComposable pi coding agent with MCP, LSP, prompt presets, and local eval telemetry
Version 0.1.16 published 2026-04-29 by spences10
Maintainers: spences10
Keywords: cli coding-agent evals lsp mcp pi pi-package sqlite telemetry
https://npm.im/my-pi

pi-gsdpi-gsdpi-gsd
Get Shit Done - Unofficial port of the renowned AI-native project-planning spec-driven toolkitGet Shit Done - Unofficial port of the renowned AI-native project-planning spec-driven toolkitGet Shit Done - Unofficial port of the renowned AI-native project-planning spec-driven toolkit
Version 2.1.4 published 2026-04-26 by GitHub Actions
Maintainers: fulgidus
Keywords: ai agent planning cli workflow get-shit-done gsd productivity project-management milestones phases spec pi-package
https://npm.im/pi-gsd

@vtstech/pi-diag@vtstech/pi-diag@vtstech/pi-diag
Diagnostics extension for Pi Coding AgentDiagnostics extension for Pi Coding AgentDiagnostics extension for Pi Coding Agent
Version 1.2.0 published 2026-04-14 by vtstech
Maintainers: vtstech
Keywords: pi-extensions
https://npm.im/@vtstech/pi-diag

@vtstech/pi-shared@vtstech/pi-shared@vtstech/pi-shared
Shared utilities for Pi Coding Agent extensionsShared utilities for Pi Coding Agent extensionsShared utilities for Pi Coding Agent extensions
Version 1.2.0 published 2026-04-14 by vtstech
Maintainers: vtstech


pi-subagents
Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification
Version 0.20.1 published 2026-04-27 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi pi-coding-agent subagents ai agents cli
https://npm.im/pi-subagents

pi-acp
ACP adapter for pi coding agent
Version 0.0.26 published 2026-04-18 by deepstereo
Maintainers: deepstereo
Keywords: acp agent-client-protocol pi-coding-agent adapter
https://npm.im/pi-acp

pi-web-access
Web search, URL fetching, GitHub repo cloning, PDF extraction, YouTube video understanding, and local video analysis for Pi coding agent
Version 0.10.6 published 2026-04-04 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi pi-coding-agent extension web-search perplexity fetch scraping
https://npm.im/pi-web-access

@rynfar/meridian
Local Anthropic API powered by your Claude Max subscription. One subscription, every agent.
Version 1.40.0 published 2026-04-26 by rynfar
Maintainers: rynfar
Keywords: meridian claude claude-max claude-code anthropic anthropic-api claude-agent-sdk ai-coding ai-assistant proxy opencode cline aider crush charmbracelet droid factory-ai pi-coding-agent open-webui llm coding-assistant opencode-claude-max-proxy
https://npm.im/@rynfar/meridian

pi-btw
A pi extension for parallel side conversations with /btw
Version 0.3.7 published 2026-04-14 by GitHub Actions
Maintainers: dbachelder
Keywords: pi-package pi-extension pi-coding-agent agent tui
https://npm.im/pi-btw

@feniix/pi-notion
Notion API extension for pi — read, search, and manage Notion pages, databases, and content
Version 2.2.2 published 2026-04-22 by feniix
Maintainers: feniix
Keywords: pi pi-package pi-extension pi-coding-agent ai notion productivity
https://npm.im/@feniix/pi-notion

@walterra/pi-charts
Vega-Lite chart extension for pi coding agent - render data visualizations as inline images
Version 0.0.5 published 2026-03-23 by GitHub Actions
Maintainers: walterra
Keywords: pi-package pi pi-coding-agent extension vega-lite charts visualization data-viz
https://npm.im/@walterra/pi-charts

pi-prompt-template-model
Prompt template model selector extension for pi coding agent
Version 0.9.3 published 2026-04-29 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi pi-coding-agent prompt-template model-selector extension
https://npm.im/pi-prompt-template-model

pi-convex
Pi extension for Convex Cloud - queries, mutations, project management, and best practices validation
Version 1.5.8 published 2026-04-27 by serlismaldonado
Maintainers: serlismaldonado
Keywords: pi-extension pi-package pi pi-coding-agent convex database backend
https://npm.im/pi-convex

pi-crew
Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration
Version 0.1.37 published 2026-04-29 by bom0792
Maintainers: bom0792
Keywords: pi-package pi pi-coding-agent teams agents multi-agent orchestration
https://npm.im/pi-crew

pi-ask-user
Interactive ask_user tool for pi-coding-agent with searchable split-pane selection UI, multi-select, and freeform input
Version 0.6.1 published 2026-04-07 by edlsh
Maintainers: edlsh
Keywords: pi-package pi pi-coding-agent extension ask ask_user interactive
https://npm.im/pi-ask-user

@kaiserlich-dev/pi-session-search
Full-text search across pi sessions with FTS5 index and overlay UI
Version 1.1.1 published 2026-02-25 by jksr194
Maintainers: jksr194
Keywords: pi-package pi-coding-agent search sessions fts5 sqlite
https://npm.im/@kaiserlich-dev/pi-session-search

pi-messenger-swarm
Swarm-first multi-agent messaging and task orchestration extension for Pi
Version 0.25.4 published 2026-04-26 by monotykamary
Maintainers: monotykamary
Keywords: pi-package pi pi-coding-agent extension swarm multi-agent agent-mesh task-orchestration subagents cli
https://npm.im/pi-messenger-swarm

pi-interactive-shell
Run AI coding agents in pi TUI overlays with interactive, hands-free, and dispatch supervision
Version 0.13.0 published 2026-04-23 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi pi-coding-agent extension interactive shell terminal tui subagent claude gemini codex
https://npm.im/pi-interactive-shell

@victor-software-house/pi-openai-proxy
OpenAI-compatible HTTP proxy for pi's multi-provider model registry
Version 4.9.3 published 2026-03-29 by GitHub Actions
Maintainers: victor-founder victoraraujo105
Keywords: openai proxy pi-coding-agent pi-package llm gateway
https://npm.im/@victor-software-house/pi-openai-proxy

mypensieve
A general-purpose, self-evolving autonomous agent OS with persistent memory across sessions
Version 0.3.6 published 2026-04-22 by GitHub Actions
Maintainers: huntersreeni
Keywords: agent ai memory autonomous pensieve pi-coding-agent llm cli telegram
https://npm.im/mypensieve

@ifi/pi-extension-subagents
Full-featured subagent orchestration extension for pi, built on top of nicobailon/pi-subagents.
Version 0.5.1 published 2026-04-28 by ifiokjr
Maintainers: ifiokjr
Keywords: chains delegation multi-agent pi pi-coding-agent pi-package subagents
https://npm.im/@ifi/pi-extension-subagents

pi-interview


context-mode
MCP plugin that saves 98% of your context window. Works with Claude Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI. Sandboxed code execution, FTS5 knowledge base, and intent-driven search.
Version 1.0.103 published 2026-04-28 by mksglu
Maintainers: mksglu
Keywords: mcp model-context-protocol claude claude-code gemini-cli vscode-copilot opencode openclaw codex-cli context-window sandbox code-execution fts5 bm25 pi-package
https://npm.im/context-mode

pi-subagents
Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification
Version 0.20.1 published 2026-04-27 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi pi-coding-agent subagents ai agents cli
https://npm.im/pi-subagents

pi-mcp-adapter
MCP (Model Context Protocol) adapter extension for Pi coding agent
Version 2.5.1 published 2026-04-24 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi mcp model-context-protocol ai coding-agent extension claude llm
https://npm.im/pi-mcp-adapter

@a5c-ai/babysitter-pi
Babysitter package for Pi Coding Agent
Version 0.1.3 published 2026-04-04 by tmuskal
Maintainers: tmuskal benihak
Keywords: pi pi-package babysitter orchestration ai-agent
https://npm.im/@a5c-ai/babysitter-pi

@ollama/pi-web-search
Web search and fetch tools for Pi agent - uses Ollama's web search and fetch APIs
Version 0.0.5 published 2026-03-28 by parthollama
Maintainers: jmorgan mchiang0610 drifkin bruce-ollama parthollama
Keywords: pi-package pi-extension web-search ollama
https://npm.im/@ollama/pi-web-search

taskplane
AI agent orchestration for pi — parallel task execution with checkpoint discipline
Version 0.28.4 published 2026-04-21 by henrylach
Maintainers: henrylach
Keywords: pi-package ai agent orchestration task-runner parallel
https://npm.im/taskplane

pi-web-access
Web search, URL fetching, GitHub repo cloning, PDF extraction, YouTube video understanding, and local video analysis for Pi coding agent
Version 0.10.6 published 2026-04-04 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi pi-coding-agent extension web-search perplexity fetch scraping
https://npm.im/pi-web-access

@plannotator/pi-extension
Plannotator extension for Pi coding agent - interactive plan review with visual annotation
Version 0.19.3 published 2026-04-29 by GitHub Actions
Maintainers: backnotprop
Keywords: pi-package plannotator plan-review ai-agent coding-agent
https://npm.im/@plannotator/pi-extension

pi-markdown-preview
Rendered markdown + LaTeX preview for pi, with terminal, browser, and PDF output
Version 0.9.6 published 2026-03-29 by omacl
Maintainers: omacl
Keywords: pi-package
https://npm.im/pi-markdown-preview

pi-gsd
Get Shit Done - Unofficial port of the renowned AI-native project-planning spec-driven toolkit
Version 2.1.4 published 2026-04-26 by GitHub Actions
Maintainers: fulgidus
Keywords: ai agent planning cli workflow get-shit-done gsd productivity project-management milestones phases spec pi-package
https://npm.im/pi-gsd

pi-powerline-footer
Powerline-style status bar extension for pi coding agent
Version 0.4.20 published 2026-04-26 by nicopreme
Maintainers: nicopreme
Keywords: pi-package pi coding-agent powerline status-bar extension
https://npm.im/pi-powerline-footer

pi-btw
A pi extension for parallel side conversations with /btw
Version 0.3.7 published 2026-04-14 by GitHub Actions
Maintainers: dbachelder
Keywords: pi-package pi-extension pi-coding-agent agent tui
https://npm.im/pi-btw

pi-lens
Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo
Version 3.8.33 published 2026-04-27 by apmantza
Maintainers: apmantza
Keywords: pi pi-extension pi-package linter biome ast-grep ruff typescript code-quality feedback type-coverage jscpd knip
https://npm.im/pi-lens

@aliou/pi-processes
![banner](https://assets.aliou.me/pi-extensions/banners/pi-processes.png)
Version 0.8.1 published 2026-04-23 by GitHub Actions
Maintainers: aliou
Keywords: pi-package pi-extension pi processes
https://npm.im/@aliou/pi-processes

@callumvass/forgeflow-dev
Dev pipeline for Pi — TDD implementation, code review, architecture, and Datadog investigations.
Version 0.36.0 published 2026-04-12 by GitHub Actions
Maintainers: callumvass
Keywords: pi-package
https://npm.im/@callumvass/forgeflow-dev

@juicesharp/rpiv-ask-user-question
Pi extension: lets the model ask you a clarifying question with structured options instead of guessing
Version 1.0.5 published 2026-04-29 by juicesharp
Maintainers: juicesharp
Keywords: pi-package pi-extension rpiv
https://npm.im/@juicesharp/rpiv-ask-user-question

@samfp/pi-memory
Persistent memory for pi — learns corrections, preferences, and patterns from sessions and injects them into future conversations.
Version 1.0.1 published 2026-04-24 by samfp
Maintainers: samfp
Keywords: pi-package extension memory learning preferences
https://npm.im/@samfp/pi-memory

dripline


**Clarifying search options**

I need a concise answer, pointing out that there isn't a dedicated search tool in the current pi setup besides install, list, config, and update options. It seems that using a manual npm search is the best route for now. I might also mention potential candidates that are relevant. Lastly, I should remember to update my to-do list once I've completed this task.


Updated #1 (pending → completed)

Find Pi extension search capability

Check whether local tools can search Pi extensions/packages, and if not, manually locate such a tool/command in installed Pi code/docs, then use it to search for relevant extensions.


Yes and no.

- **No built-in Pi extension search command** found.
- Current `pi` CLI here has: `install`, `remove`, `update`, `list`, `config`.
- So I looked manually in local Pi docs/code, then used **`npm search`** as the practical package search tool.

Best hits for your use case:

1. **pi-crew**
   - “coordinated AI teams, workflows, worktrees, and async task orchestration”
2. **pi-messenger-swarm**
   - “swarm-first multi-agent messaging and task orchestration”
3. **pi-subagents**
   - “delegating tasks to subagents with chains, parallel execution”
4. **@ifi/pi-extension-subagents**
   - “full-featured subagent orchestration”
5. **taskplane**
   - “parallel task execution with checkpoint discipline”
6. **@a5c-ai/babysitter-pi**
   - orchestration/babysitter angle
7. **pi-btw**
   - lighter parallel side conversations, probably too weak for your target

Most relevant for your plan:
- **pi-crew**
- **pi-messenger-swarm**
- **taskplane**
- maybe **pi-subagents** if you want simpler delegation over full orchestration

Important distinction:
- `pi-side-agents` = tmux/worktree-heavy async children
- `pi-subagents` family = delegated sub-process/subagent workflows
- `pi-crew` / `pi-messenger-swarm` sound closer to **hierarchical orchestrator + workers**

If you want, next step I can:
- inspect these package READMEs locally via npm metadata,
- compare them against your target architecture,
- rank best fit with tradeoffs.


good, save npm search as a skill for later pi extension searches


bash

find /home/sebas/.agents/skills -maxdepth 2 -name SKILL.md | sed -n '1,80p'


---
name: memory-write
description: Save a durable high-signal memory into agents-database
---

# memory-write

## Use When

- new information is likely useful beyond current chat or task
- saving a decision, preference, project fact, reusable source/artifact, or handoff summary
- user asks to remember something durable

## Do Not Use When

- content is trivial, redundant, ephemeral, or likely useless later
- content is secret unless user explicitly asked to store it

## Required Workflow

1. If useful context may already exist, optionally check first:
   - `curl -fsSL "${AGENTS_DB_API:-http://100.116.176.16:8091}/api/search?q=<query>&scope=global&scope=project&limit=10"`
2. Choose best memory type:
   - `profile`: stable user preference, priority, recurring constraint
   - `decision`: chosen approach or operating rule
   - `project`: durable project fact or invariant
   - `artifact`: reusable source, claim, reference, output
   - `episode`: concise session summary, blocked state, handoff context
3. Build a concise payload with:
   - required: `type`, `scope`, `title`, `content`
   - recommended when known: `subtype`, `project_id`, `repo_id`, `task_id`, `run_id`, `source_ref`, `origin_agent`, `url`, `domain`, `metadata`
4. Save it with the helper:
   - `~/.agents/skills/memory-write/memory-write --type <type> --scope <scope> --title "<title>" --content "<content>"`
5. Confirm the created memory id and what was stored.

## Quick Examples

```bash
~/.agents/skills/memory-write/memory-write \
  --type profile \
  --subtype working_preference \
  --scope global \
  --title "User prefers concise status updates" \
  --content "Sebas prefers short, direct updates with business impact first." \
  --source-ref "conversation:2026-04-17" \
  --origin-agent personal-agent

~/.agents/skills/memory-write/memory-write \
  --type decision \
  --subtype operating_rule \
  --scope global \
  --title "Agents should save durable high-signal memory opportunistically" \
  --content "Treat agents-database as shared durable memory, not only search." \
  --metadata '{"source":"conversation"}'
```

## Rules

- prefer one strong memory over many weak ones
- keep `title` short and searchable
- keep `content` factual and compact
- use `episode` for summaries, not for every chat turn
- include `url` and `domain` for web-derived artifacts when known
- include `project_id`, `repo_id`, `task_id`, and `run_id` when context exists


---
name: memory-read
description: Read persisted research memory, claims, and tasks
---

# personal-memory-search

## Workflow

1. Execute:
   - `curl -fsSL "${AGENTS_DB_API:-http://100.116.176.16:8091}/api/search?q=<query>&scope=global&scope=project&limit=20"`
2. Return matching runs, claims, and tasks from the JSON response.
3. Prefer reuse of prior work before starting a new run.


**Creating a skill file**

I need to create a skill, and I think it would be smart to save relevant details about it. I could put the skill in the directory /.agents/skills/pi-extension-search/SKILL.md. Including some npm search commands could be useful too. Maybe I should also prepare a helper script to make the process easier? It seems like keeping the skill file simple will help avoid unnecessary complications. Let's see how I can make it all come together!

write

---
name: pi-extension-search
description: Search npm for Pi extensions/packages when evaluating add-ons or orchestration tools
---

# pi-extension-search

## Use When

- user asks for Pi extensions, Pi packages, or add-ons
- you need alternatives to an installed extension
- you need to discover packages for orchestration, search, memory, UI, or workflow support in Pi

## Workflow

1. Confirm whether built-in Pi CLI supports package search:
   - `pi --help`
   - If no search command exists, use npm search.
2. Run focused npm searches with Pi package keywords:
   - `npm search --long --searchlimit=50 keywords:pi-package`
   - `npm search --long --searchlimit=50 keywords:pi-coding-agent`
   - `npm search --long --searchlimit=50 pi-coding-agent <topic>`
3. Narrow by topic as needed:
   - orchestration: `npm search --long --searchlimit=50 pi orchestration agent`
   - subagents: `npm search --long --searchlimit=50 pi subagents`
   - memory: `npm search --long --searchlimit=50 pi memory`
   - search/web: `npm search --long --searchlimit=50 pi web search`
4. Return:
   - package name
   - one-line fit summary from npm output
   - why it may fit the user goal
   - top candidates with tradeoffs
5. If the user wants installation, suggest:
   - `pi install npm:<package-name>`

## Notes

- Pi CLI here exposes install/remove/update/list/config, not package search.
- `npm search` is the practical discovery path.
- Prefer packages with explicit `pi-package`, `pi-extension`, or `pi-coding-agent` keywords.
- For multi-agent workflows, compare `pi-side-agents` against `pi-subagents`, `pi-crew`, `pi-messenger-swarm`, and `taskplane` when relevant.


Successfully wrote 1657 bytes to /home/sebas/.agents/skills/pi-extension-search/SKILL.md


bash

~/.agents/skills/memory-write/memory-write --type artifact --subtype local_skill --scope global --title "pi-extension-search skill" --content "Local skill added at /home/sebas/.agents/skills/pi-extension-search/SKILL.md. Purpose: discover Pi extensions/packages via npm search when Pi CLI lacks built-in package search. Core commands: npm search --long --searchlimit=50 keywords:pi-package ; keywords:pi-coding-agent ; pi-coding-agent <topic>." --source-ref "local-file:/home/sebas/.agents/skills/pi-extension-search/SKILL.md" --origin-agent personal-agent


pi-extension-search skill

Local skill added at /home/sebas/.agents/skills/pi-extension-search/SKILL.md. Purpose: discover Pi extensions/packages via npm search when Pi CLI lacks built-in package search. Core commands: npm search --long --searchlimit=50 keywords:pi-package ; keywords:pi-coding-agent ; pi-coding-agent <topic>.

Summary: Local skill added at /home/sebas/.agents/skills/pi-extension-search/SKILL.md. Purpose: discover Pi extensions/packages via npm search when Pi CLI lacks built-in package search. Co…


Done.

Created skill:
- `/home/sebas/.agents/skills/pi-extension-search/SKILL.md`

Saved memory:
- `mem_5895611b217c4c5db83b7aa9e7399e1e`

Use later by loading that skill when extension/package discovery comes up.


now see the findings for best match. tmux feature is a must because id like to have just one agent that orchestrates and if that looses ssh connectivity the subagents keep owrking on the server


**Exploring package metadata**

I think I need to search for relevant packages, maybe by inspecting their READMEs. I can use a command like `npm view` to check specific details. So, using `npm view <package-name> readme` would allow me to see the README contents. If I find something interesting, I might proceed to install it too. I'll just inspect the remote metadata and see what valuable information I can extract!

todo

Compare Pi orchestration extensions for tmux-resilient workflow

Inspect top candidate Pi packages for multi-agent orchestration with tmux/server persistence, then rank best fit for a single orchestrator whose children keep running after SSH disconnect.


Created #2: Compare Pi orchestration extensions for tmux-resilient workflow (pending)

Find Pi extension search capability


bash

for p in pi-crew pi-messenger-swarm taskplane pi-subagents @ifi/pi-extension-subagents @a5c-ai/babysitter-pi pi-btw; do echo '===== '"$p"' ====='; npm view "$p" name version description keywords repository.url homepage dist.tarball 2>/dev/null; echo; done

for p in pi-crew pi-messenger-swarm taskplane pi-subagents @ifi/pi-extension-subagents @a5c-ai/babysitter-pi pi-btw; do echo '===== '"$p"' README HEAD ====='; npm view "$p" readme 2>/dev/null | sed -n '1,120p'; echo; done


===== pi-crew =====
name = 'pi-crew'
version = '0.1.38'
description = 'Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration'
keywords = [
  'pi-package',
  'pi',
  'pi-coding-agent',
  'teams',
  'agents',
  'multi-agent',
  'orchestration'
]
repository.url = 'git+https://github.com/baphuongna/pi-crew.git'
homepage = 'https://github.com/baphuongna/pi-crew#readme'
dist.tarball = 'https://registry.npmjs.org/pi-crew/-/pi-crew-0.1.38.tgz'

===== pi-messenger-swarm =====
name = 'pi-messenger-swarm'
version = '0.25.4'
description = 'Swarm-first multi-agent messaging and task orchestration extension for Pi'
keywords = [
  'pi-package',
  'pi',
  'pi-coding-agent',
  'extension',
  'swarm',
  'multi-agent',
  'agent-mesh',
  'task-orchestration',
  'subagents',
  'cli'
]
repository.url = 'git+https://github.com/monotykamary/pi-messenger-swarm.git'
homepage = 'https://github.com/monotykamary/pi-messenger-swarm#readme'
dist.tarball = 'https://registry.npmjs.org/pi-messenger-swarm/-/pi-messenger-swarm-0.25.4.tgz'

===== taskplane =====
name = 'taskplane'
version = '0.28.4'
description = 'AI agent orchestration for pi — parallel task execution with checkpoint discipline'
keywords = [
  'pi-package',
  'ai',
  'agent',
  'orchestration',
  'task-runner',
  'parallel'
]
repository.url = 'git+https://github.com/HenryLach/taskplane.git'
homepage = 'https://github.com/HenryLach/taskplane#readme'
dist.tarball = 'https://registry.npmjs.org/taskplane/-/taskplane-0.28.4.tgz'

===== pi-subagents =====
name = 'pi-subagents'
version = '0.20.1'
description = 'Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification'
keywords = [
  'pi-package',
  'pi',
  'pi-coding-agent',
  'subagents',
  'ai',
  'agents',
  'cli'
]
repository.url = 'git+https://github.com/nicobailon/pi-subagents.git'
homepage = 'https://github.com/nicobailon/pi-subagents#readme'
dist.tarball = 'https://registry.npmjs.org/pi-subagents/-/pi-subagents-0.20.1.tgz'

===== @ifi/pi-extension-subagents =====
name = '@ifi/pi-extension-subagents'
version = '0.5.1'
description = 'Full-featured subagent orchestration extension for pi, built on top of nicobailon/pi-subagents.'
keywords = [
  'chains',
  'delegation',
  'multi-agent',
  'pi',
  'pi-coding-agent',
  'pi-package',
  'subagents'
]
repository.url = 'git+https://github.com/ifiokjr/oh-pi.git'
homepage = 'https://github.com/ifiokjr/oh-pi/tree/main/packages/subagents'
dist.tarball = 'https://registry.npmjs.org/@ifi/pi-extension-subagents/-/pi-extension-subagents-0.5.1.tgz'

===== @a5c-ai/babysitter-pi =====
name = '@a5c-ai/babysitter-pi'
version = '0.1.3'
description = 'Babysitter package for Pi Coding Agent'
keywords = [ 'pi', 'pi-package', 'babysitter', 'orchestration', 'ai-agent' ]
repository.url = 'git+https://github.com/a5c-ai/babysitter.git'
homepage = 'https://github.com/a5c-ai/babysitter/tree/main/plugins/babysitter-pi#readme'
dist.tarball = 'https://registry.npmjs.org/@a5c-ai/babysitter-pi/-/babysitter-pi-0.1.3.tgz'

===== pi-btw =====
name = 'pi-btw'
version = '0.3.7'
description = 'A pi extension for parallel side conversations with /btw'
keywords = [ 'pi-package', 'pi-extension', 'pi-coding-agent', 'agent', 'tui' ]
repository.url = 'git+https://github.com/dbachelder/pi-btw.git'
homepage = 'https://github.com/dbachelder/pi-btw#readme'
dist.tarball = 'https://registry.npmjs.org/pi-btw/-/pi-btw-0.3.7.tgz'


===== pi-crew README HEAD =====
# pi-crew

`pi-crew` is a Pi extension/package for coordinated AI teams: autonomous routing, manual slash-command controls, durable run state, artifacts, async/background execution, optional worktree isolation, resource management, validation, import/export, dashboard helpers, and safe API interop.

NPM package:

```text
pi-crew
```

GitHub repository:

```text
https://github.com/baphuongna/pi-crew
```

## Status

`pi-crew` is published on npm and implemented with safe execution defaults and product-oriented foundations.

Current highlights:

- one main Pi tool: `team`
- autonomous delegation policy injection before agent start
- metadata-aware `recommend` action for routing, decomposition, fanout hints, async/worktree suggestions
- configurable autonomy profiles: `manual`, `suggested`, `assisted`, `aggressive`
- builtin agents, teams, and workflows
- user/project/builtin resource discovery with priority `builtin < user < project`
- resource format support for routing metadata: `triggers`, `useWhen`, `avoidWhen`, `cost`, `category`
- durable run state: manifest, tasks, events, artifacts, imports/exports
- foreground workflow scheduler
- detached async/background runner
- stale async PID detection
- active run summary and async completion notifications in Pi sessions
- real child Pi worker execution by default, with explicit scaffold/dry-run opt-out
- child Pi JSON output parsing for final text, usage, and event counts
- retryable model fallback attempts per task
- aggregate usage totals in status/summary
- progress, summary, prompt, result, log, diff, patch, export artifacts
- task packets, verification/green-contract evidence, policy decision artifacts, and task graph metadata
- opt-in git worktree isolation per task
- worktree branch mismatch detection
- dirty worktree preservation unless `force` is explicitly set
- cancel/resume lifecycle operations
- forget/prune cleanup operations with explicit confirmation
- export/import portable run bundles
- resource create/update/delete with backups, dry-run, reference checks, and optional reference updates
- resource validation and doctor checks
- project initialization for `.pi` layout and `.gitignore`
- config show/update with user/project scope and nested unset support
- safe API interop for manifest/task/event/heartbeat/claim/mailbox operations
- realpath containment for run/import/artifact/transcript/mailbox/agent state reads and writes, including symlink escape protection
- read-only state APIs avoid creating mailbox files when only inspecting delivery or mailbox state
- run-level and task-level mailbox files with validation/repair support
- `/team-manager` interactive helper
- `/team-dashboard` custom TUI overlay with progress preview, action shortcuts, and reload
- `parallel-research` team/workflow for dynamic `Source/pi-*` fanout and parallel shard exploration
- observability metrics: per-session Counter/Gauge/Histogram registry, JSONL sink, `/team-metrics`, dashboard metrics pane, Prometheus/OTLP exporters (OTLP opt-in)
- reliability hardening: heartbeat gradient watcher, opt-in retry executor with attempt trace, crash-recovery detection, deadletter queue
- background `Agent`/`crew_agent` completion wake-up so parent sessions can automatically join completed subagent results
- package polish: `schema.json`, TypeScript semantic check, strip-types import smoke, cross-platform CI workflow, dry-run package verification

## Install

From npm:

```bash
pi install npm:pi-crew
```

From the workspace root for local development:

```bash
pi install ./pi-crew
```

Optional config bootstrap after npm install:

```bash
pi-crew
```

Optional config bootstrap from a local clone:

```bash
node ./pi-crew/install.mjs
```

Local verification from this package:

```bash
cd pi-crew
npm run ci
```

## Runtime safety model

By default, `run` launches each crew task as a separate child Pi process. This matches the subagent model from `pi-subagents`: the parent session orchestrates while worker sessions execute independently and stream durable output back to run state.

Use scaffold/dry-run mode only when you explicitly want prompts/artifacts without launching workers:

```json
{
  "runtime": { "mode": "scaffold" }
}
```

or disable workers globally:

```json
{
  "executeWorkers": false
}
```

Worktree mode is opt-in:

```json
{
  "action": "run",

===== pi-messenger-swarm README HEAD =====
<p>
  <img src="https://raw.githubusercontent.com/monotykamary/pi-messenger-swarm/main/banner.png" alt="pi-messenger-swarm" width="1100">
</p>

# Pi Messenger (Swarm Mode)

Pi Messenger is a file-based multi-agent coordination extension for Pi.

- Agents in different terminals can join the same mesh
- Each Pi session gets its own default session channel
- Named channels like `#memory` remain durable shared spaces
- Feed events, tasks, archives, and message routing are channel-scoped
- Main agents can spawn dynamic subagents with custom roles/personas/objectives
- No daemon required (all state is file-backed)

This swarm-first fork is inspired by and built upon the original project by Nico Bailon:
https://github.com/nicobailon/pi-messenger

[![npm version](https://img.shields.io/npm/v/pi-messenger-swarm?style=for-the-badge)](https://www.npmjs.com/package/pi-messenger-swarm)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)

## Screenshots

| Swarm Details                              | Swarm Messenger                                |
| ------------------------------------------ | ---------------------------------------------- |
| ![Swarm Details](assets/swarm_details.jpg) | ![Swarm Messenger](assets/swarm_messenger.jpg) |
| Memory Channel                             | Session Channel                                |
| ![Memory Channel](assets/memory.jpg)       | ![Session Channel](assets/session.jpg)         |

## Install

From npm:

```bash
pi install npm:pi-messenger-swarm
```

From git (Pi package settings):

```json
{
  "packages": ["git:github.com/monotykamary/pi-messenger-swarm@main"]
}
```

> Tip: after release tags are published, pin to a version tag instead of `main` (for example `@vX.Y.Z`).

## Quick Start

Join the messenger and start collaborating in your session channel:

```bash
pi-messenger-swarm join
pi-messenger-swarm send #memory "Investigating auth timeout in refresh flow"
pi-messenger-swarm task create --title "Investigate auth timeout" --content "Repro + fix"
pi-messenger-swarm task claim task-1
pi-messenger-swarm task progress task-1 "Found race in refresh flow"
pi-messenger-swarm task done task-1 "Fixed refresh lock + tests"
```

Spawn a specialized subagent:

```bash
pi-messenger-swarm spawn --role "Packaging Gap Analyst" --persona "Skeptical market researcher" "Find productization gaps in idea aggregation tools"
```

## Channel Model

Pi Messenger is now **channel-first**.

### Session channels

Each Pi session gets a dedicated default channel, generated as a human-friendly phrase such as:

- `#quiet-river`
- `#wild-viper`
- `#ember-owl`

The same Pi `sessionId` restores the same session channel when reopened.

### Named channels

By default, a durable named channel is created:

- `#memory` — cross-session knowledge, notes, decisions, and async handoff

You can create additional named channels as needed.

You can also create additional named channels explicitly with `join`.

### Durable channel posting

Channel messages are durable even when nobody is listening.

Posting to a channel means:

1. append to that channel's feed
2. try live inbox delivery to agents currently joined to that channel

That makes channels useful as async coordination logs for later agents to pick up.

### Session switching and resume

If Pi switches or resumes sessions inside the same live messenger instance, messenger rebinds to the resumed Pi session:

- restores the correct session channel
- drops stale old session-channel membership
- restarts watchers on the correct inbox
- keeps named channels like `#memory`

## Core Actions

### Coordination

- `join`
- `status`
- `list`
- `whois`
- `feed`
- `set_status`

===== taskplane README HEAD =====
# Taskplane

Multi-agent AI orchestration for coding with [pi](https://github.com/badlogic/pi-mono) — parallel task execution, mono- and poly-repo support, fresh-context worker loops, cross-model reviews, automated merges and a killer dashboard!

> **Status:** Initial release.

## What It Does

Taskplane orchesrates batches of task to help you turn ideas into high-quality code using a proven process of:

have an idea >> create a spec >> create tasks >> orchestrate tasks >> evaluate the outcome

For background on Taskplane's creation see [Author's Note on Medium](https://medium.com/@henry_49934/welcome-to-taskplane-authors-note-ad3a0278fdd3).

### Taskplane has:
- A skill for creating tasks that the Taskplane orchestrator can run
- prompt.md/status.md task definitions for persistent memory store
- Support for both monorepo and polyrepo projects
- Complete parallelized worktree isolation with dependency graphing and segment-level repo isolation
- 4 agent types: supervisor, worker, reviewer, and merger
- A deterministic orchestration engine to drive repeatable positive agent outcomes at scale
- A simple file-based mail system so agents can communicate with each other
- A killer locally-run web-based dashboard so you can see everything that's going on

<img src="docs/images/orchrun-wave2of4-2lanes-withstatus.png" alt="image of taskplane dashboard" width="50%">

### STEP 1: Create the tasks
Taskplane turns your coding project into an AI-managed task orchestration system. You simply ask your agent to create tasks using the built-in "create-taskplane-tasks" skill. This skill provides an opinionated task definition template designed to drive successful coding outcomes. Tasks define both the prompt.md and the status.md files that together act as the persistent memory store that allows AI coding agents to survive context resets and succeed with very long running tasks that would typically exhaust an agent's context window.

### STEP 2: Run batches of tasks
Taskplane works out the dependency map for an entire batch of tasks then orchestrates them in waves, lanes, and tasks with appropriate parallelization and serialization. Taskplane can do this for both monorepo and polyrepo projects. For polyrepo projects, Taskplane additionally subdivides tasks into repo-aligned segments and uses a segmentation dependency map (DAG) to manage proper repo/worktree isolation and allow for dynamic segment expansion so worker agents can ask the supervisor agent to add additional segments to the dependency map in real time if required.

### Key Features

- **Task Orchestrator** — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges into a dedicated orch branch — your working branch stays stable until you choose to integrate.
- **Persistent Worker Context** — Workers handle all steps in a single context, auto-detecting the model's context window. Only iterates on context overflow. Dramatic reduction in spawn count and token cost.
- **Worker-Driven Inline Reviews** — Workers invoke a `review_step` tool at step boundaries. Reviewer agents spawn with full telemetry. REVISE feedback is addressed inline without losing context.
- **Supervisor Agent** — Conversational supervisor monitors batch progress, handles failures, and can invoke orchestrator commands autonomously (resume, integrate, pause, abort).
- **Web Dashboard** — Live browser-based monitoring via `taskplane dashboard`. SSE streaming, lane/task progress, reviewer activity, merge telemetry, batch history.
- **Structured Tasks** — PROMPT.md defines the mission, steps, and constraints. STATUS.md tracks progress. Agents follow the plan, not vibes.
- **Checkpoint Discipline** — Step boundary commits ensure work is never lost, even if a worker crashes mid-task.
- **Cross-Model Review** — Reviewer agent uses a different model than the worker agent (highly recommended, not enforced). Independent quality gate before merge.

## Installation

Taskplane is a pi package. You need Node.js 22+, pi and Git installed first.

### Prerequisites

| Dependency | Required | Notes |
|-----------|----------|-------|
| [Node.js](https://nodejs.org/) ≥ 22 | Yes | Runtime |
| [pi](https://github.com/badlogic/pi-mono) | Yes | Agent framework |
| [Git](https://git-scm.com/) | Yes | Version control, worktrees |

IMPORTANT: If you just installed pi, make sure you've configured at least one model provider and tested before installing Taskplane.

### Option A: Global Install (all projects - recommended)

```bash
pi install npm:taskplane
```

### Option B: Single Project-Local Install

```bash
cd my-project
pi install -l npm:taskplane
```

## Quickstart

### 1. Initialize a project (to scaffold settings)
This step assumes you have installed Taskplane using one of the above options.

(NOTE: if 'my-project' is a monorepo, be sure to run git init first. Taskplane uses git worktrees to isolate agent coding until you're ready to merge back to your default branch.)

```bash
cd my-project
taskplane init
```
You'll answer a few questions. You can usually just accept the defaults.

This creates: config files in `.pi/`, agent prompts, two example tasks, and adds `.gitignore` entries for runtime artifacts. On first install, init bootstraps global preferences at `~/.pi/agent/taskplane/preferences.json` with thinking defaults set to `high` for worker & reviewer, and off for merger. Init auto-detects whether you're in a monorepo or a polyrepo workspace. See the [install tutorial](docs/tutorials/install.md) for workspace mode and other scenarios.

Already have a task folder (for example `docs/task-management`)? Use:

```bash
taskplane init --preset full --tasks-root docs/task-management
```

When `--tasks-root` is provided, example task packets are skipped by default. Add `--include-examples` if you explicitly want examples in that folder.

### 2. Check your install with taskplane doctor

Verify the installation and scaffolding. You should have all green checkboxes if everything was successful:

```bash
taskplane doctor
```

### 3. Launch the dashboard (recommended)

In a separate terminal:

```bash
taskplane dashboard
```

Opens a live web dashboard at `http://localhost:8099` with real-time batch monitoring.

### 4. Run your first orchestration

```bash
pi
```

Inside the pi session:

```

===== pi-subagents README HEAD =====

# pi-subagents

`pi-subagents` lets Pi delegate work to focused child agents. Use it for code review, scouting, implementation, parallel audits, saved workflows, background jobs, and anything else that benefits from a second or third set of model eyes.

https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1

## Installation

```bash
pi install npm:pi-subagents
```

That is the only required step. You can add optional pieces later.

## Try this first

You do not need to create agents, write config, or learn slash commands. After installing, ask Pi for delegation in plain language:

```text
Use reviewer to review this diff.
```

```text
Ask oracle for a second opinion on my current plan.
```

```text
Use scout to understand this code based on our discussion then ask me clarification questions.
```

```text
Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.
```

That is enough to start.

## What happens

Pi is the parent session. A subagent is a focused child Pi session with its own job.

When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation. Background runs keep working and can be checked later.

Installing the extension does not start an automatic reviewer in the background. It gives Pi a delegation tool. If you want every implementation reviewed, say that in your prompt or put it in your project instructions:

```text
When you finish implementing, run a reviewer subagent before summarizing.
```

## Good first prompts

These cover most day-to-day use:

```text
Ask oracle for a second opinion on my current plan. Challenge assumptions and tell me what I might be missing.
```

```text
Use oracle to help solve this hard bug. Have it inspect the code and propose the best next move before we edit anything.
```

```text
Run parallel reviewers on this diff. I want one focused on correctness, one on tests, and one on unnecessary complexity.
```

```text
Have worker implement this approved plan. Afterward, run parallel reviewers, summarize their feedback, and apply the fixes that make sense.
```

```text
Use scout to understand the auth flow, then have planner turn that into an implementation plan.
```

Those are ordinary Pi requests. Pi decides whether to call `subagent`, which agent to use, and whether a chain or parallel run makes sense.

## Common workflows

| Want | Ask naturally |
|------|---------------|
| Get a second opinion | “Ask oracle to review this plan and challenge assumptions.” |
| Solve a hard problem | “Use oracle to investigate this bug before we edit.” |
| Review a diff | “Use reviewer to review this diff.” |
| Run parallel reviewers | “Run reviewers for correctness, tests, and cleanup.” |
| Implement then review | “Implement this, then review it.” |
| Execute a plan carefully | “Have worker implement this approved plan, then run reviewers and apply the feedback.” |
| Scout before planning | “Use scout to inspect the auth flow before planning.” |
| Run in the background | “Run this in the background.” |
| Browse agents | “Show me the available subagents.” |
| Use a saved workflow | “Run the review chain on this branch.” |
| See running work | “Show subagent status.” |
| Check setup | “Check whether subagents are configured correctly.” |

The extension ships with builtin agents you can use immediately.

## Builtin agents in plain English

| Agent | Use it when you want... |
|-------|--------------------------|
| `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks, and where another agent should start. |
| `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
| `planner` | A concrete implementation plan from existing context. It should read and plan, not edit code. |
| `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
| `reviewer` | Code review and small fixes. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
| `context-builder` | A stronger setup pass before planning: gathers code context and writes handoff material such as `context.md` and `meta-prompt.md`. |
| `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
| `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |

A simple rule of thumb: use `scout` before you understand the code, `researcher` before you trust external facts, `planner` before a bigger change, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.

## Changing a builtin agent's model

You do not need to copy builtin agent files just to change their model.

For one run, put the override in the command:

```text
/run reviewer[model=anthropic/claude-sonnet-4] "Review this diff"

===== @ifi/pi-extension-subagents README HEAD =====
<p>
  <img src="banner.png" alt="@ifi/pi-extension-subagents" width="1100">
</p>

# @ifi/pi-extension-subagents

Pi extension for delegating tasks to subagents with chains, parallel execution, TUI clarification, and async support.

Built on top of [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) (MIT).

https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1

## Installation

```bash
pi install npm:@ifi/pi-extension-subagents
```

Or install it as part of the full oh-pi bundle:

```bash
npx @ifi/oh-pi
```

Or use the package installer directly:

```bash
npx @ifi/pi-extension-subagents
npx @ifi/pi-extension-subagents --local
```

To remove:

```bash
npx @ifi/pi-extension-subagents --remove
```

## Agents

Agents are markdown files with YAML frontmatter that define specialized subagent configurations.

**Agent file locations:**

| Scope   | Path                                                                                | Priority |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Builtin | Bundled with this package in `agents/`                                                                                | Lowest   |
| User    | `~/.pi/agent/agents/{name}.md`                                                                                | Medium   |
| Project | `~/.pi/agent/subagents/project-agents/<mirrored-workspace>/agents/{name}.md` (searches mirrored parent workspaces); legacy `.pi/agents/{name}.md` is opt-in | Highest  |

Use `agentScope` parameter to control discovery: `"user"`, `"project"`, or `"both"` (default; project takes priority).

<!-- {=subagentsProjectAgentStorageOverview} -->

Subagents stores project-scope agents and chains in shared pi storage by default under a
workspace-mirrored path, so repositories stay clean while still supporting parent-workspace lookup
for nested projects. Legacy repo-local `.pi/agents/` storage remains available as an explicit
project-mode override.

<!-- {/subagentsProjectAgentStorageOverview} -->

**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, `artist`, `frontend-designer`, and `multimodal-summariser`. They load at lowest priority so any user or project agent with the same name overrides them. Builtin agents appear with a `[builtin]` badge in listings and cannot be modified through management actions (create a same-named user agent to override instead).

> **Note:** The `researcher` agent uses `web_search`, `fetch_content`, and `get_search_content` tools which require the [pi-web-access](https://github.com/nicobailon/pi-web-access) extension. Install it with `pi install npm:pi-web-access`.
>
> **Note:** `artist` and `multimodal-summariser` work best when the runtime can access the relevant media files directly. `artist` prioritizes production-ready SVG and concrete image briefs when raster generation is not available as a tool.

**Agent frontmatter:**

```yaml
---
name: scout
description: Fast codebase recon
tools: read, grep, find, ls, bash, mcp:chrome-devtools # mcp: requires pi-mcp-adapter
extensions: # absent=all, empty=none, csv=allowlist
category: quick-discovery # optional delegated routing category
thinking: high # off, minimal, low, medium, high, xhigh
skill: safe-bash, chrome-devtools # comma-separated skills to inject
output: context.md # writes to {chain_dir}/context.md
defaultReads: context.md # comma-separated files to read
defaultProgress: true # maintain progress.md
interactive: true # (parsed but not enforced in v1)
---
Your system prompt goes here (the markdown body after frontmatter).
```

The `thinking` field sets a default extended thinking level for the agent. At runtime it's appended as a `:level` suffix to the model string (e.g., `claude-sonnet-4-5:high`). If the model already has a thinking suffix (from a chain-clarify override), the agent's default is not double-applied.

The optional `category` field lets agents participate in delegated startup routing. When a runtime override or explicit `model` is not present, subagents can resolve a concrete model from `~/.pi/agent/extensions/adaptive-routing/config.json`.

Delegated selection is dynamic rather than provider-hardcoded: it considers the models currently available in the session, optional provider disable lists, role overrides such as `subagent:<agent-name>`, best-effort usage headroom from `usage-tracker`, context-window fit, and benchmark-backed task scores.

To inspect why a delegated startup pick resolved the way it did, use `@ifi/pi-extension-adaptive-routing`'s `/route why <category|role-override> [task text]` command.

**Extension sandboxing**

Use `extensions` in frontmatter to control which extensions a subagent can access:

```yaml
# Field absent: all extensions load (default behavior)

# Empty field: no extensions
extensions:

# Allowlist specific extensions
extensions: /abs/path/to/ext-a.ts, /abs/path/to/ext-b.ts
```

Semantics:

- `extensions` absent → all extensions load
- `extensions:` empty → `--no-extensions`
- `extensions: a,b` → `--no-extensions --extension a --extension b`

When `extensions` is present, it takes precedence over extension paths implied by `tools` entries.

**MCP Tools**

Agents can use MCP server tools directly (requires the [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) extension). Add `mcp:` prefixed entries to the `tools` field:

```yaml

===== @a5c-ai/babysitter-pi README HEAD =====

===== pi-btw README HEAD =====
# pi-btw

A small [pi](https://github.com/badlogic/pi-mono) extension that adds a `/btw` side conversation channel.

`/btw` opens a real pi sub-session with coding-tool access, and it runs immediately even while the main agent is still busy.

![BTW overlay example](docs/btw-overlay.png)

## What it does

- opens a parallel side conversation without interrupting the main run
- runs that side conversation as a real pi sub-session with `read` / `bash` / `edit` / `write` tool access
- keeps a continuous BTW thread by default
- supports `/btw:tangent` for a contextless side thread that does not inherit the current main-session conversation
- opens a focused BTW modal shell with its own composer and transcript
- keeps the BTW overlay open while you switch focus back to the main editor with `Alt+/`
- keeps BTW thread entries out of the main agent's future context
- supports BTW-only model and thinking overrides without changing the main thread settings
- lets you inject the full thread, or a summary of it, back into the main agent
- optionally saves an individual BTW exchange as a visible session note with `--save`

## Install

### From npm (after publish)

```bash
pi install npm:pi-btw
```

### From git

```bash
pi install git:github.com/dbachelder/pi-btw
```

Then reload pi:

```text
/reload
```

### From a local checkout

```bash
pi install /absolute/path/to/pi-btw
```

## Usage

```text
/btw what file defines this route?
/btw how would you refactor this parser?
/btw --save summarize the last error in one sentence
/btw:new let's start a fresh thread about auth
/btw:tangent brainstorm from first principles without using the current chat context
/btw:model openai gpt-5-mini openai-responses
/btw:thinking low
/btw:inject implement the plan we just discussed
/btw:summarize turn that side thread into a short handoff
/btw:clear
```

## Commands

### `/btw [--save] <question>`

- runs right away
- works while pi is busy
- creates or reuses a real BTW sub-session instead of a one-off completion call
- continues the current BTW thread
- opens or refreshes the focused BTW modal shell
- streams into the BTW modal transcript/status surface
- persists the BTW exchange as hidden thread state
- with `--save`, also saves that single exchange as a visible session note

## Overlay controls

- `Alt+/` toggles focus between BTW and the main editor without closing the overlay
- `Ctrl+Alt+W` is a fallback focus toggle for terminals that do not deliver `Alt+/` as a usable shortcut
- `Esc` still dismisses BTW immediately while the overlay is focused
- BTW now opens top-centered so the main session remains visible underneath it

### `/btw:new [question]`

- clears the current BTW thread
- starts a fresh thread that still inherits the current main-session context
- optionally asks the first question in the new thread immediately
- if no question is provided, opens a fresh BTW modal ready for the next prompt

### `/btw:tangent [--save] <question>`

- starts or continues a contextless tangent thread
- does not inherit the current main-session conversation
- if you switch from `/btw` to `/btw:tangent` (or back), the previous side thread is cleared so the modes do not mix
- opens or refreshes the same focused BTW modal shell
- with `--save`, also saves that single exchange as a visible session note

### `/btw:clear`

- dismisses the BTW modal/widget
- clears the current BTW thread

### `/btw:inject [instructions]`

- sends the full BTW thread back to the main agent as a user message
- if pi is busy, queues it as a follow-up
- clears the BTW thread after sending

### `/btw:summarize [instructions]`

- summarizes the BTW thread with the current effective BTW model
- always runs summarize with thinking off, even if BTW chat is using a thinking override
- injects the summary into the main agent
- if pi is busy, queues it as a follow-up
- clears the BTW thread after sending

### `/btw:model [<provider> <model> <api> | clear]`

- with no args, shows the current effective BTW model and whether it is inherited or overridden
- with values, sets a BTW-only model override


**Determining tmux support**

I need to figure out if tmux is supported, so I'll search through readmes and look for any mentions of tmux, detached sessions, or background processes. Maybe I'll check the source code too, though I'm not sure that's necessary. A good plan could be using a combination of npm view to check the readme and grep for terms like tmux, ssh, detached, background, or worktree. That might help clarify things!

for p in pi-crew pi-messenger-swarm taskplane pi-subagents @ifi/pi-extension-subagents @a5c-ai/babysitter-pi pi-btw; do echo '===== '"$p"' signals ====='; npm view "$p" readme 2>/dev/null | grep -Ein 'tmux|detach|detached|background|ssh|session|daemon|persist|worktree|terminal|tty|tmux' | sed -n '1,80p'; echo; done

tmp=$(mktemp -d); cd "$tmp" || exit 1; for p in pi-crew pi-messenger-swarm taskplane pi-subagents @ifi/pi-extension-subagents @a5c-ai/babysitter-pi pi-btw; do echo '===== '"$p"' package files ====='; npm pack "$p" >/dev/null 2>&1 || { echo pack-failed; continue; }; tgz=$(ls -1 *.tgz | tail -1); mkdir x; tar -xzf "$tgz" -C x; grep -RIn 'tmux\|detached\|background\|spawn\|worktree\|session channel\|file-based\|daemon' x/package 2>/dev/null | head -80; rm -rf x *.tgz; echo; done


===== pi-crew signals =====
3:`pi-crew` is a Pi extension/package for coordinated AI teams: autonomous routing, manual slash-command controls, durable run state, artifacts, async/background execution, optional worktree isolation, resource management, validation, import/export, dashboard helpers, and safe API interop.
25:- metadata-aware `recommend` action for routing, decomposition, fanout hints, async/worktree suggestions
32:- detached async/background runner
34:- active run summary and async completion notifications in Pi sessions
41:- opt-in git worktree isolation per task
42:- worktree branch mismatch detection
43:- dirty worktree preservation unless `force` is explicitly set
58:- observability metrics: per-session Counter/Gauge/Histogram registry, JSONL sink, `/team-metrics`, dashboard metrics pane, Prometheus/OTLP exporters (OTLP opt-in)
60:- background `Agent`/`crew_agent` completion wake-up so parent sessions can automatically join completed subagent results
98:By default, `run` launches each crew task as a separate child Pi process. This matches the subagent model from `pi-subagents`: the parent session orchestrates while worker sessions execute independently and stream durable output back to run state.
116:Worktree mode is opt-in:
123:  "workspaceMode": "worktree"
127:By default, worktree mode requires a clean leader repository. Dirty task worktrees are preserved unless cleanup is called with `force: true`.
159:  "requireCleanWorktreeLeader": true,
165:    "allowWorktreeSuggestion": true,
224:- Foreground child-process runs continue in the Pi extension process and return control to chat immediately, so large workflows do not block the interactive session. They are interrupted on session shutdown. Use `async: true` only for intentionally detached runs that may survive the current session.
225:- Background `Agent`/`crew_agent` runs notify the parent session when they reach a terminal state; the parent can then call `get_subagent_result`/`crew_agent_result` and continue the original task.
234:- `widgetPlacement`/`widgetMaxLines` keep the persistent active-run widget compact.
235:- `dashboardPlacement: "right"` is the default for `/team-dashboard`; automatic overlay opening is opt-in because Pi custom overlays can be modal/focus-capturing in some terminals.
280:Use it for complex multi-file work, planning, implementation, tests, reviews, security audits, research, async/background runs, and worktree-isolated execution.
306:| `worktrees` | List run worktree metadata |
309:| `cleanup` | Clean run worktrees; dirty worktrees are preserved unless forced |
349:Run with worktrees:
357:  "workspaceMode": "worktree"
396:/team-run [--team=name] [--workflow=name] [--async] [--worktree] <goal>
403:/team-worktrees <runId>
416:/team-autonomy [status|on|off|manual|suggested|assisted|aggressive] [--prefer-async] [--no-worktree-suggest]
484:- cleanup run worktrees
602:<crewRoot>/worktrees/{runId}/{taskId}
663:.crew/worktrees/
669:.pi/teams/worktrees/

===== pi-messenger-swarm signals =====
9:- Agents in different terminals can join the same mesh
10:- Each Pi session gets its own default session channel
14:- No daemon required (all state is file-backed)
27:| Memory Channel                             | Session Channel                                |
28:| ![Memory Channel](assets/memory.jpg)       | ![Session Channel](assets/session.jpg)         |
50:Join the messenger and start collaborating in your session channel:
71:### Session channels
73:Each Pi session gets a dedicated default channel, generated as a human-friendly phrase such as:
79:The same Pi `sessionId` restores the same session channel when reopened.
85:- `#memory` — cross-session knowledge, notes, decisions, and async handoff
102:### Session switching and resume
104:If Pi switches or resumes sessions inside the same live messenger instance, messenger rebinds to the resumed Pi session:
106:- restores the correct session channel
107:- drops stale old session-channel membership
171:pi-messenger-swarm send #memory "Claimed task-4, touching src/auth/session.ts"
224:├── tasks/                       # Per-session task storage
225:│   ├── session-abc.jsonl      # Task event log (created, claimed, done, etc.)
226:│   └── session-abc/           # Task specs directory
229:├── agents/                      # Per-session spawned agent storage
230:│   ├── session-abc.jsonl      # Agent event log (spawned, completed, failed, stopped)
231:│   └── session-abc/           # Agent definition files
251:  "description": "Cross-session knowledge and insights"
278:- tasks are now stored per session at `.pi/messenger/tasks/<session>.jsonl`
279:- session channels are phrase-based instead of `session-*` timestamp-like ids

===== taskplane signals =====
13:For background on Taskplane's creation see [Author's Note on Medium](https://medium.com/@henry_49934/welcome-to-taskplane-authors-note-ad3a0278fdd3).
17:- prompt.md/status.md task definitions for persistent memory store
19:- Complete parallelized worktree isolation with dependency graphing and segment-level repo isolation
28:Taskplane turns your coding project into an AI-managed task orchestration system. You simply ask your agent to create tasks using the built-in "create-taskplane-tasks" skill. This skill provides an opinionated task definition template designed to drive successful coding outcomes. Tasks define both the prompt.md and the status.md files that together act as the persistent memory store that allows AI coding agents to survive context resets and succeed with very long running tasks that would typically exhaust an agent's context window.
31:Taskplane works out the dependency map for an entire batch of tasks then orchestrates them in waves, lanes, and tasks with appropriate parallelization and serialization. Taskplane can do this for both monorepo and polyrepo projects. For polyrepo projects, Taskplane additionally subdivides tasks into repo-aligned segments and uses a segmentation dependency map (DAG) to manage proper repo/worktree isolation and allow for dynamic segment expansion so worker agents can ask the supervisor agent to add additional segments to the dependency map in real time if required.
35:- **Task Orchestrator** — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges into a dedicated orch branch — your working branch stays stable until you choose to integrate.
36:- **Persistent Worker Context** — Workers handle all steps in a single context, auto-detecting the model's context window. Only iterates on context overflow. Dramatic reduction in spawn count and token cost.
54:| [Git](https://git-scm.com/) | Yes | Version control, worktrees |
76:(NOTE: if 'my-project' is a monorepo, be sure to run git init first. Taskplane uses git worktrees to isolate agent coding until you're ready to merge back to your default branch.)
104:In a separate terminal:
118:Inside the pi session:
131:For a single task with full worktree isolation, dashboard, and reviews:
137:This uses the same orchestrator infrastructure as a full batch — isolated worktree, orch branch, supervisor, dashboard, inline reviews — but for just one task.
141:When you're in pi, type /taskplane-settings. Near the top you'll see the 4 agents. By default, Taskplane installs with the agent models set to inherit whatever model your pi session is currently using. The best thing you can do is configure the reviewer agent to use a different model provider. If you're using Claude for coding, then consider using OpenAI for the reviews.
145:### Pi Session Commands
149:| `/orch [<areas\|paths\|all>]` | No args: detect state & guide (onboarding, batch planning, etc.); with args: execute tasks via isolated worktrees |
156:| `/orch-sessions` | List active worker sessions |
181:  │ Lane 1  │ │ Lane 2 │ │ Lane 3 │    ← Git worktrees
199:**How it works:** Tasks are sorted into dependency waves. Each wave runs in parallel across lanes (git worktrees). Workers handle all steps in a single context, calling `review_step` at step boundaries for inline reviews. Completed lanes merge into a dedicated orch branch. A supervisor agent monitors progress and can autonomously resume, integrate, or abort. When the batch completes, use `/orch-integrate` to bring the results into your working branch (or configure auto-integration).

===== pi-subagents signals =====
7:`pi-subagents` lets Pi delegate work to focused child agents. Use it for code review, scouting, implementation, parallel audits, saved workflows, background jobs, and anything else that benefits from a second or third set of model eyes.
43:Pi is the parent session. A subagent is a focused child Pi session with its own job.
45:When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation. Background runs keep working and can be checked later.
47:Installing the extension does not start an automatic reviewer in the background. It gives Pi a delegation tool. If you want every implementation reviewed, say that in your prompt or put it in your project instructions:
90:| Run in the background | “Run this in the background.” |
109:| `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
123:For a persistent override, use `/agents`:
153:Background runs keep working after control returns to you. They show completion notifications and can be inspected with:
189:`pi-subagents` works without `pi-intercom`. Install `pi-intercom` only if you want child agents to talk back to the parent Pi session while they are running.
195:Most users do not call `intercom` directly. After `pi-intercom` is installed, `pi-subagents` can automatically give child agents a private coordination channel back to the parent session.
200:Run this implementation in the background. If the worker gets blocked or needs a product decision, have it ask me through intercom.
209:- `ask`: the child needs a decision or clarification from the parent session
212:Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
214:If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking `/subagents-status`, interrupting the run, or nudging the child.
224:At this point, you know enough to use the plugin. The rest of this README is reference material for exact command syntax, custom agents, saved chains, worktrees, and configuration.
291:### Background and forked runs
293:Add `--bg` to run in the background:
301:Add `--fork` to start each child from a real branched session created from the parent’s current leaf:
324:- `Enter` runs in the foreground, or in the background if background is toggled on
331:- `b` toggles background execution
355:| Task Input | Enter the shared task and launch with fork/background/worktree toggles where supported. |
588:{ agent: "scout", task: "...", skill: "tmux, safe-bash" }
632:// Chain without TUI, suitable for background execution
645:// Worktree isolation
649:], worktree: true }
713:| `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
715:| `context` | `fresh \| fork` | `fresh` | `fork` creates real branched sessions from the parent leaf. |
716:| `chainDir` | string | temp chain dir | Persistent directory for chain artifacts. |
719:| `async` | boolean | false | Background execution. Chains require `clarify: false`. |
724:| `share` | boolean | false | Upload session export to GitHub Gist. |
725:| `sessionDir` | string | derived | Override session log directory. |
727:`context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or the branched child session cannot be created. It never silently downgrades to `fresh`.
729:Sequential and parallel chain tasks accept `agent`, `task`, `cwd`, `output`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`.
740:## Worktree isolation
742:Parallel agents can clobber each other if they edit the same checkout. `worktree: true` gives each parallel child its own git worktree branched from `HEAD`.
748:], worktree: true }
755:  ], worktree: true },
764:- `node_modules/` is symlinked into each worktree when present
766:- configured `worktreeSetupHook` must return valid JSON before timeout
768:After a worktree parallel step completes, per-agent diff stats are appended to the output and full patch files are written to artifacts. Worktrees and temp branches are cleaned up in `finally` blocks.
780:Makes top-level calls use background execution when the request does not explicitly set `async`. Callers can still force foreground with `async: false` unless `forceTopLevelAsync` is enabled.
788:Forces depth-0 single, parallel, and chain runs into background mode and bypasses clarify UI by forcing `clarify: false`. Nested calls keep their own inherited settings.
803:### `defaultSessionDir`
806:{ "defaultSessionDir": "~/.pi/agent/sessions/subagent/" }
809:Session directory precedence is: `params.sessionDir`, then `config.defaultSessionDir`, then a directory derived from the parent session. Sessions are always enabled.
837:Bridge activation also requires `pi-intercom` to be installed and enabled, a targetable current session name or fallback alias, and `pi-intercom` in any explicit agent `extensions` allowlist.
841:### `worktreeSetupHook`
845:  "worktreeSetupHook": "./scripts/setup-worktree.mjs",
846:  "worktreeSetupHookTimeoutMs": 45000
850:The hook runs once per created worktree. Paths must be absolute, `~/...`, or repo-relative; bare command names are rejected.
852:stdin is a JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `index`, `runId`, and `baseCommit`. stdout must be one JSON object, for example:
858:`syntheticPaths` must be relative to the worktree root. They are removed before diff capture so helper files do not pollute patches. Tracked files are never excluded; marking a tracked path as synthetic fails setup. Default timeout is `30000` ms.
870:Debug artifacts live under `{sessionDir}/subagent-artifacts/` or a user-scoped temp artifact directory. Per task you may see:
879:Session files are stored under a per-run session directory. With `context: "fork"`, each child starts with `--session <branched-session-file>` produced from the parent’s current leaf. That is a real session fork, not an injected summary.
881:Async completions notify only the originating session. The result watcher emits `subagent:async-complete`, and the extension consumes that event to render completion notifications.
893:`status.json` powers the widget and `/subagents-status`. `events.jsonl` contains wrapper events plus child Pi JSON events annotated with run and step metadata. `output-<n>.log` is a live human-readable tail. Fallback information is persisted so background runs are debuggable after completion.
903:## Session sharing
905:Pass `share: true` to export a full session to HTML, upload it to a secret GitHub Gist through your `gh` credentials, and return a `https://shittycodingagent.ai/session/?<gistId>` URL.
911:This is disabled by default. Session data may contain source code, paths, environment variables, credentials, or other sensitive output. You need `gh` installed and authenticated.
917:By default, nesting is limited to two levels: main session → subagent → sub-subagent. Deeper calls are blocked with guidance to complete the current task directly.
945:The result watcher emits `subagent:async-complete`; `index.ts` registers the notification handler that consumes it. Control/attention events are surfaced as visible parent notices and persisted for async runs. With `pi-intercom`, needs-attention notices and grouped parent-side subagent result deliveries can reach the orchestrator over intercom.
977:| `subagent-runner.ts` | Detached async runner. |
978:| `async-execution.ts` | Background launch support. |
983:| `worktree.ts` | Git worktree isolation. |

===== @ifi/pi-extension-subagents signals =====
90:Delegated selection is dynamic rather than provider-hardcoded: it considers the models currently available in the session, optional provider disable lists, role overrides such as `subagent:<agent-name>`, best-effort usage headroom from `usage-tracker`, context-window fit, and benchmark-backed task scores.
137:The MCP adapter's metadata cache must be populated for direct tools to work. On the first session with a new MCP server, tools will only be available through the `mcp` proxy. Restart Pi after the first session and direct tools become available.
197:### Background Execution
199:Add `--bg` at the end of any slash command to run in the background:
207:Background tasks run asynchronously and notify you when complete. Check status with `subagent_status`.
312:- **Session Logs**: JSONL session files with paths shown in output
314:- **Async Widget**: Lightweight TUI widget shows background run progress
315:- **Session-scoped Notifications**: Async completions only notify the originating session
325:All modes support background/async execution. For programmatic async, use `clarify: false, async: true`. For interactive async, use `clarify: true` and press `b` in the TUI to toggle background mode before running. Chains with parallel steps (`{ parallel: [...] }`) run concurrently with configurable `concurrency` and `failFast` options.
343:- `Enter` - Run (foreground) or launch in background if `b` is toggled on
350:- `b` - Toggle background/async execution (all modes) — shows `[b]g:ON` when enabled
411:{ agent: "scout", task: "...", skill: "tmux, safe-bash" }
486:// Async chain with parallel step (runs in background)
510:Agent definitions are not loaded into LLM context by default. Management actions let the LLM discover, inspect, create, and modify agent and chain definitions at runtime through the `subagent` tool — no manual file editing or restart required. Newly created agents are immediately usable in the same session. Set `action` and omit execution payloads (`task`, `chain`, `tasks`).
584:| `chainDir`        | string                          | `<tmpdir>/pi-chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h)                                  |
587:| `async`           | boolean                         | false                     | Background execution (requires `clarify: false` for chains)                                                |
592:| `share`           | boolean                         | false                     | Upload session to GitHub Gist (see [Session Sharing](#session-sharing))                                    |
593:| `sessionDir`      | string                          | -                         | Override session log directory (takes precedence over `defaultSessionDir` and parent-session-derived path) |
663:### `defaultSessionDir`
665:`defaultSessionDir` sets the fallback directory used for session logs. Eg:
669:	"defaultSessionDir": "~/.pi/agent/sessions/subagent/"
673:Session root resolution follows this precedence:
675:1. `params.sessionDir` from the `subagent` tool call
676:2. `config.defaultSessionDir`
677:3. Derived from parent session (stored alongside parent session file)
679:Sessions are always enabled — every subagent run gets a session directory for tracking.
760:Location: `{sessionDir}/subagent-artifacts/` or `<tmpdir>/pi-subagent-artifacts/`
769:## Session Logs
771:Session files (JSONL) are stored under a per-run session directory. Directory selection follows the same precedence as session root resolution: explicit `sessionDir` > `config.defaultSessionDir` > parent-session-derived path. The session file path is shown in output.
773:## Session Sharing
777:1. Export the full session (all tool calls, file contents, outputs) to an HTML file
779:3. Return a shareable URL (`https://shittycodingagent.ai/session/?<gistId>`)
781:**This is disabled by default.** Session data may contain sensitive information like source code, file paths, environment variables, or credentials that appear in tool outputs.
819:By default nesting is limited to **2 levels**: `main session → subagent → sub-subagent`. Any deeper `subagent` calls are blocked and return an error with guidance to the calling agent.
869:├── async-execution.ts            # Async/background execution support
877:├── subagent-runner.ts            # Async runner (detached process)

===== @a5c-ai/babysitter-pi signals =====

===== pi-btw signals =====
5:`/btw` opens a real pi sub-session with coding-tool access, and it runs immediately even while the main agent is still busy.
12:- runs that side conversation as a real pi sub-session with `read` / `bash` / `edit` / `write` tool access
14:- supports `/btw:tangent` for a contextless side thread that does not inherit the current main-session conversation
20:- optionally saves an individual BTW exchange as a visible session note with `--save`
69:- creates or reuses a real BTW sub-session instead of a one-off completion call
73:- persists the BTW exchange as hidden thread state
74:- with `--save`, also saves that single exchange as a visible session note
79:- `Ctrl+Alt+W` is a fallback focus toggle for terminals that do not deliver `Alt+/` as a usable shortcut
81:- BTW now opens top-centered so the main session remains visible underneath it
86:- starts a fresh thread that still inherits the current main-session context
93:- does not inherit the current main-session conversation
96:- with `--save`, also saves that single exchange as a visible session note
129:- changing `/btw:model` or `/btw:thinking` disposes the current BTW sub-session and applies the new settings on the next BTW prompt while preserving the hidden thread
133:### Real sub-session model
135:BTW is implemented as an actual pi sub-session with its own in-memory session state, transcript events, and tool surface.
137:- contextual `/btw` threads seed that sub-session from the current main-session branch while filtering out BTW-visible notes from the parent context
138:- `/btw:tangent` starts the same BTW UI in a contextless mode with no inherited main-session conversation
141:- the overlay transcript/status line is driven from sub-session events, so tool activity, streaming deltas, failures, and recovery are all visible without scraping rendered output
142:- handoff commands (`/btw:inject` and `/btw:summarize`) read from the BTW sub-session thread rather than maintaining a separate manual transcript model
146:Inside the BTW modal composer, slash handling is split at the BTW/session boundary:
149:- any other slash-prefixed input is routed through the BTW sub-session's normal `prompt()` path
150:- this means ordinary pi slash commands like `/help` are handled by the sub-session instead of being rejected by a modal-only fallback
151:- if the sub-session cannot handle a slash command, BTW surfaces the real sub-session failure through the transcript/status state instead of inventing an "unsupported slash input" warning
153:This keeps BTW-owned lifecycle commands explicit while giving the side conversation the same slash-command surface as the underlying sub-session.
159:BTW exchanges are persisted in the session as hidden custom entries so they:
164:- preserve the current BTW-only model and thinking overrides for that session history
169:If you use `--save`, that one BTW exchange is also written as a visible custom message in the session transcript.