# pi-subagents

`pi-subagents` is a Pi extension package that runs generic subagent tasks in separate child sessions and ships workflow prompt templates plus the wrapper code needed to execute those runs.

## Install

Local path:

```bash
pi install /absolute/path/to/subagents
```

Git:

```bash
pi install https://gitea.rwiesner.com/pi/pi-subagents
```

## Resources

- Extension: `./index.ts`
- Prompts: `./prompts/*.md`

## Runner modes

- default: background child process runner
- optional tmux runner: set `{"runner":"tmux"}` in `.pi/subagents.json` or `~/.pi/agent/subagents.json`

## What a subagent run gets

- delegated task text
- selected model
- optional working directory

Child runs are normal Pi sessions.

## Presets

Subagent presets are discovered from markdown files. Locations:

- global: `~/.pi/agent/subagents/*.md`
- nearest project: `.pi/subagents/*.md` (nearest ancestor directory)

Project presets override global presets by name. No built-in presets or roles are bundled with this package.

Preset frontmatter fields:

- `name` (required)
- `description` (required)
- `model` (optional; provider/id)
- `tools` (optional; comma-separated list or array)

Preset body becomes the child session system prompt. The `tools` field maps directly to Pi CLI `--tools` and limits which built-in tools are available to the child run.

## Tools provided

- `subagent` — foreground single or parallel runs using named presets
- `background_agent` — detached process-backed run that returns immediately with a handle
- `background_agent_status` — query background run counts and status

## Requirements

- default process runner: no tmux requirement
- optional tmux runner: `tmux` must be available on `PATH`

## Development

```bash
npm install
npm test
```