---
slug: "pi-your-subagents"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/jandrikus/pi-your-subagents@main/README.md"
repo: "https://github.com/jandrikus/pi-your-subagents"
source_file: "README.md"
branch: "main"
---
# pi-your-subagents

A [pi](https://pi.dev) extension that provides configurable, user-extensible subagents using agent definitions from the [Awesome Agents Library](https://github.com/jandrikus/awesome-agents-library).

## Agent Sources

Agents are defined as `.yml` files in two locations:

| Location | Path | Purpose |
|----------|------|---------|
| Global | `~/.pi/agents/` | Default agents sync here on first run, user can customize |
| Local | `.pi/agents/` | Project-specific overrides (takes precedence) |

Local agents take precedence over global agents with the same name. Each `.yml` file contains the full agent definition: name, label, tools, system prompt, parameters, etc.

Agent definitions are loaded from the [Awesome Agents Library](https://github.com/jandrikus/awesome-agents-library). To add agents, copy `.yml` files from the library into `~/.pi/agents/` (global) or `.pi/agents/` (per-project).

## Features

- **Background execution** — Subagents run as `pi` child processes with live TUI progress widgets
- **Local precedence** — `.pi/agents/agent.yml` overrides `~/.pi/agents/agent.yml`
- **Agent control panel** — `Ctrl+Shift+1` to stop, cancel, or view running agents
- **Activity timeout** — Detects stuck processes (10 min) and marks as failed

## Agent YAML Format

```yaml
name: my-agent
label: My Agent
promptSnippet: One-line description for the parent LLM
promptGuidelines:
  - "When to use this agent..."
tools:
  - read
  - grep
model: ""            # empty = use parent model
extensions: []       # empty = no extensions
taskTemplate: "Do X: {param1}"
parameters:
  - name: param1
    description: "What param1 means"
    required: true
systemPrompt: >
  System prompt for the agent when spawned.
```

## Installation

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

## Configuration

Extension settings live in `~/.pi/config/pi-your-subagents/settings.json`:

```json
{
  "keybinding": 1
}
```

| Setting | Default | Description |
|---------|---------|-------------|
| `keybinding` | `1` | Number key for control panel (`Ctrl+Shift+N`) |

## License

Apache-2.0