254 lines
8.8 KiB
Markdown
254 lines
8.8 KiB
Markdown
---
|
|
created: 2026-06-15
|
|
modified: 2026-06-15
|
|
type: note
|
|
tags:
|
|
- ai
|
|
- pi
|
|
- subagent
|
|
- pi-subagents
|
|
aliases: []
|
|
---
|
|
|
|
# Pi Subagent System
|
|
|
|
Persistent named subagents with provider-pinned KV cache continuity.
|
|
|
|
## What It Is
|
|
|
|
Pi-subagents (@tintinweb v0.10.2) lets you spawn named, persistent subagents that:
|
|
|
|
- **Run in background** — don't block the main session
|
|
- **Keep their context** — resume later with full conversation history
|
|
- **Pin to a provider** — KV cache stays warm across resume calls (= massive token savings)
|
|
- **Have persistent memory** — `memory: project` gives each agent its own memory directory
|
|
- **Survive session restarts** — patched to keep agents alive 24h, not 10 minutes
|
|
|
|
---
|
|
|
|
## Key Concepts
|
|
|
|
### Named Agents
|
|
|
|
Every subagent gets a **human-readable name** so you can reference it later:
|
|
|
|
- `coder-login` — coder-pro working on auth
|
|
- `searcher-1` — chat-search for web lookups
|
|
- `obsidian-docs` — obsidian agent for note editing
|
|
|
|
Multiple instances of the same type can run simultaneously:
|
|
|
|
- `coder-login` + `coder-nav-bar` — two coder-pro agents, different tasks
|
|
- `searcher-1` + `searcher-2` — parallel web searches
|
|
|
|
### Provider Pinning
|
|
|
|
Each agent is pinned to a specific OpenRouter provider via `only: [...]` in models.json. This ensures:
|
|
|
|
- **KV cache continuity** — same provider = cache hits on resume
|
|
- **Predictable latency** — always route through the same serving host
|
|
- **Cost control** — token savings when context prefix is cached
|
|
|
|
See [[Pi Agent Extensions & Skills#models.json]] for the full routing table.
|
|
|
|
### Persistent Memory
|
|
|
|
Agents with `memory: project` in their frontmatter get a persistent directory:
|
|
|
|
```
|
|
.pi/agent-memory/<agent-name>/ ← per-project, committed to git
|
|
.pi/agent-memory-local/<agent-name>/ ← per-project, gitignored
|
|
~/.pi/agent-memory/<agent-name>/ ← global, across all projects
|
|
```
|
|
|
|
Memory survives across resume calls. Agents build up knowledge over time.
|
|
|
|
### Session-Scoped Registry
|
|
|
|
Agents belong to a **pi session** (per-project directory). When you `/new` or `/resume`, the session's agents are available.
|
|
|
|
---
|
|
|
|
## Creating Agents
|
|
|
|
### Ask the LLM
|
|
|
|
Simply describe what you need. The LLM will ask for a name if you don't provide one:
|
|
|
|
```
|
|
You: "Find all authentication files"
|
|
LLM: "What should I name this agent?"
|
|
You: "auth-finder"
|
|
LLM: *spawns agent, saves to registry*
|
|
"Created 'auth-finder' (chat-search, Google). ID: 7efad0d8"
|
|
```
|
|
|
|
### Agent Types Available
|
|
|
|
| Type | Model | Provider | Memory | Tools | Use For |
|
|
|------|-------|----------|--------|-------|---------|
|
|
| `chat-search` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Web search, quick lookups |
|
|
| `coder-basic` | deepseek-chat | DeepInfra | project | read, bash, write, grep, find | Simple code edits |
|
|
| `coder-pro` | deepseek-v4-pro | DeepInfra | project | read, bash, write, grep, find, edit | Complex architecture |
|
|
| `code-analysis` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, grep, find | Security review, analysis |
|
|
| `code-ingest` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Scan/ingest docs, GitHub |
|
|
| `database` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write, grep | SQL, schema design |
|
|
| `devops-basic` | deepseek-chat | DeepInfra | project | read, bash, write, grep, find | Docker, YAML, NixOS |
|
|
| `devops-pro` | deepseek-v4-pro | DeepInfra | project | read, bash, write, grep, find, edit | Complex infrastructure |
|
|
| `document-writer` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write | Documents, letters |
|
|
| `file-ops` | qwen-coder-32b-instruct | opencode-go | project | read, bash, grep, find, write | Filesystem, drives |
|
|
| `home-automation` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write, grep | MQTT, Home Assistant |
|
|
| `image-maker` | flux-1-schnell | Venice | project | read, bash, write | Image generation |
|
|
| `iot-coder` | qwen-coder-32b-instruct | opencode-go | project | read, bash, write, grep, find | Arduino, ESP32 |
|
|
| `iot-hardware` | kimi-k2.6 | Moonshot AI | project | read, bash, grep, find | Hardware specs, boards |
|
|
| `obsidian` | deepseek-r1-distill-qwen-14b | opencode-go | project | read, bash, write, grep, find | Obsidian notes |
|
|
| `research` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Web search, docs |
|
|
| `video-analyze` | qwen-2.5-vl | Alibaba | project | read, bash, grep, find | Video/image analysis |
|
|
| `vscode-setup` | qwen-3-coder-next | StreamLake | project | read, bash, grep, find | VS Code, AI tooling |
|
|
| `Explore` | haiku/inherit | default | — | read, bash, grep, find, ls | Fast codebase search (built-in) |
|
|
| `Plan` | inherit | default | — | read, bash, grep, find, ls | Implementation planning (built-in) |
|
|
| `general-purpose` | inherit | default | — | all tools | General tasks (built-in) |
|
|
|
|
---
|
|
|
|
## Managing Agents
|
|
|
|
### List Agents
|
|
|
|
Type `/agents` to open the interactive menu:
|
|
|
|
```
|
|
Running agents (2) — 1 running, 1 done
|
|
Agent types (21)
|
|
Create new agent
|
|
Settings
|
|
```
|
|
|
|
Select **"Running agents"** to see active agents with status, tool uses, and duration.
|
|
|
|
### View Conversation
|
|
|
|
From `/agents` → "Running agents" → select an agent:
|
|
|
|
- **Live scrolling overlay** of the agent's full conversation
|
|
- **Auto-follows** new output
|
|
- **Press `x`** to stop a running agent
|
|
- **Scroll up** to pause auto-follow
|
|
|
|
### Resume an Agent
|
|
|
|
```
|
|
You: "Resume auth-finder and also check the logout module"
|
|
LLM: *looks up agent ID from context*
|
|
Agent({ subagent_type: "chat-search", resume: "7efad0d8-...", prompt: "Also check the logout module" })
|
|
```
|
|
|
|
The agent continues with its full context preserved. Provider KV cache is warm.
|
|
|
|
### Steer a Running Agent
|
|
|
|
```
|
|
You: "Tell auth-finder to focus on the API routes only"
|
|
LLM: steer_subagent({ agent_id: "7efaf0d8-...", message: "Focus on API routes only, ignore UI" })
|
|
```
|
|
|
|
The agent receives the message after its current tool execution and adjusts course.
|
|
|
|
### Delete an Agent
|
|
|
|
```
|
|
You: "Delete auth-finder"
|
|
LLM: *removes from registry, aborts if running*
|
|
"Deleted 'auth-finder'"
|
|
```
|
|
|
|
Or delete all agents for a session:
|
|
|
|
```
|
|
You: "Clear all subagents for computer-software"
|
|
LLM: *removes all matching entries*
|
|
"Deleted 4 subagents from session 'computer-software'"
|
|
```
|
|
|
|
---
|
|
|
|
## Function Calls
|
|
|
|
### Create
|
|
|
|
```
|
|
Agent({
|
|
subagent_type, // string — agent type (e.g. "coder-pro")
|
|
prompt, // string — the task
|
|
description, // string — 3-5 word summary
|
|
model?, // string — provider/model override
|
|
thinking?, // string — off|minimal|low|medium|high|xhigh
|
|
max_turns?, // number — max agentic turns (default: unlimited)
|
|
run_in_background?, // boolean — run async (default: false)
|
|
resume?, // string — agent ID to resume a previous session
|
|
isolated?, // boolean — no extension/MCP tools
|
|
isolation?, // "worktree" — run in isolated git worktree
|
|
inherit_context? // boolean — fork parent conversation into agent
|
|
})
|
|
```
|
|
|
|
### Retrieve
|
|
|
|
```
|
|
get_subagent_result({
|
|
agent_id, // string — the agent ID from spawn notification
|
|
wait?, // boolean — block until complete (default: false)
|
|
verbose? // boolean — include full conversation (default: false)
|
|
})
|
|
```
|
|
|
|
### Steer
|
|
|
|
```
|
|
steer_subagent({
|
|
agent_id, // string — running agent ID
|
|
message // string — message injected after current tool execution
|
|
})
|
|
```
|
|
|
|
### Compress
|
|
|
|
```
|
|
compress_for_agent({
|
|
content // string — content >20K chars to compress via Headroom
|
|
})
|
|
// Returns: { compressed, originalLength, compressedLength, tokensBefore, tokensAfter, savingsPercent }
|
|
```
|
|
|
|
---
|
|
|
|
## Token Savings
|
|
|
|
The entire purpose is to **minimize context tokens** on the API provider:
|
|
|
|
| Scenario | Context Uploaded | Cost |
|
|
|----------|-----------------|------|
|
|
| Fresh agent every request | Full system prompt + context (~10K tokens) | ~$0.50-1.00 per request |
|
|
| Resume same agent | Only new prompt (~100 tokens) + cached prefix hits KV cache | ~$0.01-0.05 per request |
|
|
| **Savings** | **90-95% reduction** | **~$0.50 vs $5.00 for 5 questions** |
|
|
|
|
---
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `~/.local/share/npm-global/lib/node_modules/@tintinweb/pi-subagents/` | Extension source |
|
|
| `~/.pi/agent/agents/*.md` | Agent type definitions (18 custom + 3 built-in) |
|
|
| `~/.pi/agent/models.json` | OpenRouter provider pinning (only: provider) |
|
|
| `.pi/agent-memory/<name>/` | Per-agent persistent memory (project scope) |
|
|
| `.pi/agent-memory-local/<name>/` | Per-agent persistent memory (gitignored) |
|
|
| `~/.pi/agent/subagents.json` | pi-subagents settings (maxConcurrent, etc.) |
|
|
|
|
## Related
|
|
|
|
- [[Pi Agent Extensions & Skills]] — full extensions/skills reference
|
|
- [[Engram Memory]] — persistent memory service on .13
|
|
- [[Headroom Compression]] — context compression via .13:8787
|
|
- [[OpenRouter Provider Routing]] — provider pinning for cache continuity
|