0xrsydn/arch-dotfiles
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

pi: add agent config, themes, subagents, and extensions

Browse source
This commit is contained in:
Rasyidan Akbar F. 2026-03-11 20:54:51 +07:00
commit b10d457e5f
16 changed files with 5832 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

9
.pi/agent/AGENTS.md Normal file
View file

@ -0,0 +1,9 @@
# Global agent context
## Environment
- This machine has `ssh` and `tailscale` installed.
- The agent can access other machines from here over the Tailscale network when needed.
- If a task needs work on a remote host, the agent may use `ssh` from this machine.
- Prefer non-destructive remote inspection first, and be explicit when commands are being run on a remote machine.
- If the target host or remote command is unclear, ask the user before connecting.

39
.pi/agent/agents/librarian.md Normal file
View file

@ -0,0 +1,39 @@
---
name: librarian
description: Explore and map the codebase, gather references, and return organized context
tools: read, grep, find, ls, bash
model: anthropic/claude-sonnet-4-6
---
You are a codebase librarian.
Your job is to explore, collect, and organize context so another agent can act without repeating all discovery.
Think of yourself as recon plus indexing.
Focus on:
- where relevant code lives
- how files connect
- important symbols, entry points, and data flow
- existing conventions or similar implementations
Tool rules:
- Prefer grep/find/ls first, then read targeted ranges.
- Bash is for read-only exploration only.
- Do not edit files.
Output format:
## Map
- Key files and why they matter
## Symbols
- Important functions, classes, types, routes, or commands
## Flow
- How the parts connect
## Reuse
- Similar existing implementations to copy from
## Start Here
- Best first files for the next agent to open

41
.pi/agent/agents/reviewer.md Normal file
View file

@ -0,0 +1,41 @@
---
name: reviewer
description: Code review specialist for bugs, risks, and maintainability
tools: read, grep, find, ls, bash
model: openai-codex/gpt-5.4:xhigh
---
You are a senior code reviewer.
Your job is to inspect code and changes for:
- correctness bugs
- edge cases
- security risks
- maintainability problems
- missing tests or validation
Tool rules:
- Use read-only investigation only.
- Bash is allowed only for read-only commands like `git diff`, `git status`, `git log`, `git show`, `npm test -- --help`, or listing files.
- Do not edit files.
- Do not run destructive commands.
Output format:
## Scope
- What you reviewed
## Critical
- Issues that should block merge
## Warnings
- Important problems to fix soon
## Suggestions
- Nice-to-have improvements
## Evidence
- Exact file paths and line numbers wherever possible
## Summary
- 2-4 sentence overall assessment

43
.pi/agent/agents/uiux-designer.md Normal file
View file

@ -0,0 +1,43 @@
---
name: uiux-designer
description: UI/UX design specialist for product flows, interaction design, and implementation-ready recommendations
tools: read, grep, find, ls
model: google-antigravity/gemini-3.1-pro-high
---
You are a UI/UX design specialist.
Your job is to turn requirements and current product context into a practical UI/UX design direction.
You do not implement changes.
You analyze flows, interaction details, information hierarchy, usability tradeoffs, and rollout shape.
Focus on:
- user journeys and interaction flow
- screen or component responsibilities
- hierarchy, affordances, and feedback states
- empty, loading, error, and edge states
- accessibility and clarity
- incremental rollout guidance for engineering
Output format:
## Goal
- Restate the user and product problem clearly
## Proposed UX/UI Direction
- Recommended approach
## Key Screens or States
- Main surfaces, components, and states to account for
## Alternatives
- Reasonable alternatives and tradeoffs
## Implementation Guidance
1. Small actionable steps for engineering
## Risks
- What could confuse users or make the design harder to ship
## Validation
- How to test whether the design works

31
.pi/agent/extensions/lsp-feedback/README.md Normal file
View file

@ -0,0 +1,31 @@
# pi lsp-feedback
Auto-detected defaults for this machine:
- `.nix` -> `~/.nix-profile/bin/nixd` + `alejandra`
- `.sh`, `.bash` -> `~/.nix-profile/bin/bash-language-server start` + `shfmt -w`
- `.lua` -> `~/.nix-profile/bin/lua-language-server` + `stylua`
## What it does
- Overrides pi `write` and `edit`
- After a file change, optionally formats the file
- Re-syncs the final file content into the language server
- Adds a compact diagnostics summary to tool output
- Shows a compact footer status only after supported LSP activity
## Commands
- `/diag path/to/file` - compact diagnostics for one file
- `/lsp-restart` - restart managed language servers
## Tool
- `lsp_diagnostics` - on-demand diagnostics for supported files
## Notes
- This MVP is intentionally compact and context-efficient.
- It stays silent on startup and only becomes visible after you touch or check a supported file.
- Whole-project diagnostics are not implemented yet.
- If you change this extension, run `/reload` in pi.

3959
.pi/agent/extensions/lsp-feedback/package-lock.json generated Normal file
View file

File diff suppressed because it is too large Load diff

42
.pi/agent/extensions/plan-mode/README.md Normal file
View file

@ -0,0 +1,42 @@
# Plan mode extension
Claude Code-style plan mode for pi.
## Features
- `/plan` toggles read-only planning mode
- `Ctrl+Alt+P` toggles plan mode on/off
- `/plan execute` runs the last approved plan in the current session with full tools restored
- `/plan execute fresh` starts a fresh session and carries the approved plan into it for execution
- extracts numbered steps from a `Plan:` section
- tracks progress with `[DONE:n]` markers during execution
- restores your previous active tool set after plan mode ends
- keeps `subagent` available in plan mode when you intentionally want to use helper agents during planning
## Commands
- `/plan`
- `/plan on`
- `/plan off`
- `/plan execute`
- `/plan execute fresh`
- `/plan status`
- `/plan clear`
## Shortcut
- `Ctrl+Alt+P` — toggle plan mode
## Behavior
When plan mode is enabled, pi switches to read-only exploration and asks the model to produce a numbered `Plan:` section.
After planning finishes, the extension shows a chooser so you can:
- execute now
- execute in a fresh session
- send custom feedback / continue discussion
- stay in plan mode
When you execute the plan in the current session, the extension restores your previous tools and asks the model to complete the steps while emitting `[DONE:n]` markers.
If you use `/plan execute fresh`, the extension creates a new session, carries over the approved plan and planner notes, restores the full tool set there, and starts execution in that fresh context.

410
.pi/agent/extensions/plan-mode/index.ts Normal file
View file

@ -0,0 +1,410 @@
import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
import { extractTodoItems, isSafeCommand, markCompletedSteps, type TodoItem } from "./utils.js";
const PLAN_FLAG = "plan-mode";
const PLAN_TODOS_WIDGET = "plan-todos";
const PLAN_CONTEXT_TYPE = "plan-mode-context";
const PLAN_EXECUTION_CONTEXT_TYPE = "plan-execution-context";
const PLAN_STATE_ENTRY = "plan-mode-state";
const PREFERRED_PLAN_TOOLS = ["read", "bash", "grep", "find", "ls", "lsp_diagnostics", "subagent"];
type PlanModeState = {
enabled: boolean;
executing: boolean;
savedTools: string[] | null;
todos: TodoItem[];
};
function getAssistantText(message: any): string {
if (!message || message.role !== "assistant" || !Array.isArray(message.content)) return "";
return message.content
.filter((part: any) => part?.type === "text" && typeof part.text === "string")
.map((part: any) => part.text)
.join("\n")
.trim();
}
export default function planModeExtension(pi: ExtensionAPI): void {
let planModeEnabled = false;
let executionMode = false;
let savedTools: string[] | null = null;
let todoItems: TodoItem[] = [];
function persistState() {
const state: PlanModeState = {
enabled: planModeEnabled,
executing: executionMode,
savedTools,
todos: todoItems,
};
pi.appendEntry(PLAN_STATE_ENTRY, state);
}
function getPlanTools(): string[] {
const allToolNames = new Set(pi.getAllTools().map((tool) => tool.name));
const tools = new Set<string>();
for (const name of PREFERRED_PLAN_TOOLS) {
if (allToolNames.has(name)) tools.add(name);
}
if (savedTools) {
for (const name of savedTools) {
if (allToolNames.has(name) && PREFERRED_PLAN_TOOLS.includes(name)) tools.add(name);
}
}
return Array.from(tools);
}
function restoreSavedTools() {
if (savedTools && savedTools.length > 0) {
pi.setActiveTools(savedTools);
}
}
function updateUi(ctx: ExtensionContext) {
if (executionMode && todoItems.length > 0) {
const completed = todoItems.filter((item) => item.completed).length;
ctx.ui.setStatus(PLAN_FLAG, `📋 ${completed}/${todoItems.length}`);
} else if (planModeEnabled) {
ctx.ui.setStatus(PLAN_FLAG, "⏸ PLAN");
} else {
ctx.ui.setStatus(PLAN_FLAG, undefined);
}
if ((planModeEnabled || executionMode) && todoItems.length > 0) {
ctx.ui.setWidget(
PLAN_TODOS_WIDGET,
todoItems.map((item) => `${item.completed ? "☑" : "☐"} ${item.step}. ${item.text}`),
);
} else {
ctx.ui.setWidget(PLAN_TODOS_WIDGET, undefined);
}
}
function enablePlanMode(ctx: ExtensionContext) {
if (!savedTools) savedTools = pi.getActiveTools();
planModeEnabled = true;
executionMode = false;
pi.setActiveTools(getPlanTools());
updateUi(ctx);
persistState();
ctx.ui.notify(`Plan mode enabled. Active tools: ${getPlanTools().join(", ")}`, "info");
}
function disablePlanMode(ctx: ExtensionContext, notify = true) {
planModeEnabled = false;
executionMode = false;
restoreSavedTools();
updateUi(ctx);
persistState();
if (notify) ctx.ui.notify("Plan mode disabled. Previous tools restored.", "info");
}
function clearPlan(ctx: ExtensionContext) {
executionMode = false;
todoItems = [];
updateUi(ctx);
persistState();
ctx.ui.notify("Stored plan cleared.", "info");
}
function showStatus(ctx: ExtensionContext) {
if (!planModeEnabled && !executionMode && todoItems.length === 0) {
ctx.ui.notify("Plan mode is off and no stored plan exists.", "info");
return;
}
const lines = [
`plan mode: ${planModeEnabled ? "on" : "off"}`,
`execution: ${executionMode ? "on" : "off"}`,
`stored steps: ${todoItems.length}`,
];
if (todoItems.length > 0) {
for (const item of todoItems) lines.push(`${item.step}. ${item.completed ? "✓" : "○"} ${item.text}`);
}
ctx.ui.notify(lines.join("\n"), "info");
}
function getLatestPlannedAssistantText(ctx: ExtensionContext): string {
const branch = ctx.sessionManager.getBranch();
for (let i = branch.length - 1; i >= 0; i--) {
const entry: any = branch[i];
if (entry?.type !== "message" || !entry.message) continue;
const text = getAssistantText(entry.message);
if (text && extractTodoItems(text).length > 0) return text;
}
return "";
}
function buildExecutionPrompt(ctx: ExtensionContext, fresh: boolean): string {
const remaining = todoItems.filter((item) => !item.completed);
const planLines = todoItems.map((item) => `${item.step}. ${item.text}${item.completed ? " [already done]" : ""}`);
const latestPlanText = getLatestPlannedAssistantText(ctx);
const sections = [
fresh
? "You are executing an approved plan in a fresh session. The earlier planning conversation is not available, so rely only on the context below."
: "Execute the approved plan in this session.",
"## Approved Plan",
planLines.join("\n"),
];
if (remaining.length > 0) {
sections.push("## Remaining Steps", remaining.map((item) => `${item.step}. ${item.text}`).join("\n"));
}
if (latestPlanText) {
sections.push("## Planner Notes", latestPlanText);
}
sections.push(
"## Execution Instructions",
[
"Inspect files before editing.",
"If the approved plan needs adjustment, explain why before making a larger change.",
"Complete the remaining steps in order.",
"After completing a step, include a [DONE:n] marker in your response.",
].join("\n"),
);
return sections.join("\n\n");
}
function startExecution(ctx: ExtensionContext) {
if (todoItems.length === 0) {
ctx.ui.notify("No stored plan found. Create one in /plan mode first.", "warning");
return;
}
planModeEnabled = false;
executionMode = true;
restoreSavedTools();
updateUi(ctx);
persistState();
ctx.ui.notify("Executing stored plan with full tools restored.", "info");
pi.sendUserMessage(buildExecutionPrompt(ctx, false));
}
async function startFreshExecution(ctx: any) {
if (todoItems.length === 0) {
ctx.ui.notify("No stored plan found. Create one in /plan mode first.", "warning");
return;
}
await ctx.waitForIdle();
const executionPrompt = buildExecutionPrompt(ctx, true);
const executionTools = savedTools && savedTools.length > 0 ? [...savedTools] : [...pi.getActiveTools()];
const carriedTodos = todoItems.map((item) => ({ ...item }));
const parentSession = ctx.sessionManager.getSessionFile();
const result = await ctx.newSession({
parentSession,
setup: async (sm: any) => {
sm.appendCustomEntry(PLAN_STATE_ENTRY, {
enabled: false,
executing: true,
savedTools: executionTools,
todos: carriedTodos,
});
},
});
if (result.cancelled) {
ctx.ui.notify("Fresh execution session cancelled.", "info");
return;
}
pi.sendUserMessage(executionPrompt);
}
pi.registerFlag("plan", {
description: "Start in read-only plan mode",
type: "boolean",
default: false,
});
pi.registerCommand("plan", {
description: "Toggle plan mode, or use /plan on|off|execute [fresh]|status|clear",
handler: async (args, ctx) => {
const action = args.trim().toLowerCase();
switch (action) {
case "":
case "toggle":
if (planModeEnabled) disablePlanMode(ctx);
else enablePlanMode(ctx);
return;
case "on":
enablePlanMode(ctx);
return;
case "off":
disablePlanMode(ctx);
return;
case "execute":
startExecution(ctx);
return;
case "execute fresh":
await startFreshExecution(ctx);
return;
case "status":
showStatus(ctx);
return;
case "clear":
clearPlan(ctx);
return;
default:
ctx.ui.notify("Usage: /plan [on|off|execute|execute fresh|status|clear]", "warning");
}
},
});
pi.registerShortcut("ctrl+alt+p", {
description: "Toggle plan mode on/off",
handler: async (ctx) => {
if (planModeEnabled) disablePlanMode(ctx);
else enablePlanMode(ctx);
},
});
pi.on("tool_call", async (event) => {
if (!planModeEnabled) return;
if (event.toolName === "edit" || event.toolName === "write") {
return { block: true, reason: "Plan mode is read-only. Disable it before modifying files." };
}
if (event.toolName === "bash") {
const command = typeof event.input?.command === "string" ? event.input.command : "";
if (!isSafeCommand(command)) {
return {
block: true,
reason: `Plan mode blocked a non read-only bash command: ${command}`,
};
}
}
});
pi.on("context", async (event) => {
if (planModeEnabled || executionMode) return;
return {
messages: event.messages.filter((message: any) => {
if (message?.customType === PLAN_CONTEXT_TYPE) return false;
if (message?.customType === PLAN_EXECUTION_CONTEXT_TYPE) return false;
return true;
}),
};
});
pi.on("before_agent_start", async () => {
if (planModeEnabled) {
return {
message: {
customType: PLAN_CONTEXT_TYPE,
display: false,
content: `[PLAN MODE ACTIVE]\nYou are in read-only planning mode.\n\nRules:\n- Do not modify files.\n- Do not use edit or write.\n- Use only read-only investigation.\n- You may use subagent when it helps planning. Prefer read-only helpers like librarian, reviewer, or uiux-designer when appropriate.\n- If requirements are unclear, ask clarifying questions before planning.\n- Produce a numbered plan under a \"Plan:\" header.\n- Call out risks, dependencies, and validation steps.`,
},
};
}
if (executionMode && todoItems.length > 0) {
const remaining = todoItems.filter((item) => !item.completed);
return {
message: {
customType: PLAN_EXECUTION_CONTEXT_TYPE,
display: false,
content:
`[EXECUTING APPROVED PLAN]\nComplete the remaining plan steps in order.\n\nRemaining steps:\n${remaining.map((item) => `${item.step}. ${item.text}`).join("\n")}\n\nAfter completing a step, include [DONE:n] in your response.`,
},
};
}
});
pi.on("turn_end", async (event, ctx) => {
if (!executionMode || todoItems.length === 0) return;
const text = getAssistantText(event.message);
if (!text) return;
if (markCompletedSteps(text, todoItems) > 0) {
updateUi(ctx);
persistState();
}
if (todoItems.length > 0 && todoItems.every((item) => item.completed)) {
executionMode = false;
updateUi(ctx);
persistState();
ctx.ui.notify("Plan execution completed.", "success");
}
});
pi.on("agent_end", async (event, ctx) => {
if (!planModeEnabled) return;
const lastAssistant = [...event.messages].reverse().find((message: any) => message?.role === "assistant");
const text = getAssistantText(lastAssistant);
if (!text) return;
const extracted = extractTodoItems(text);
if (extracted.length === 0) return;
todoItems = extracted;
updateUi(ctx);
persistState();
if (!ctx.hasUI) return;
const choice = await ctx.ui.select("Plan ready - what next?", [
"Execute the plan now",
"Execute in a fresh session",
"Send custom feedback / continue discussion",
"Stay in plan mode",
]);
if (choice === "Execute the plan now") {
startExecution(ctx);
return;
}
if (choice === "Execute in a fresh session") {
await startFreshExecution(ctx);
return;
}
if (choice === "Send custom feedback / continue discussion") {
const feedback = await ctx.ui.editor(
"What should Pi do next?",
"Refine the plan by ...",
);
if (feedback?.trim()) {
pi.sendUserMessage(feedback.trim());
}
}
});
pi.on("session_start", async (_event, ctx) => {
const branch = ctx.sessionManager.getBranch();
const stateEntry = branch
.filter((entry: any) => entry.type === "custom" && entry.customType === PLAN_STATE_ENTRY)
.pop() as { data?: PlanModeState } | undefined;
if (stateEntry?.data) {
planModeEnabled = stateEntry.data.enabled ?? false;
executionMode = stateEntry.data.executing ?? false;
savedTools = stateEntry.data.savedTools ?? null;
todoItems = stateEntry.data.todos ?? [];
} else if (pi.getFlag("--plan") === true || pi.getFlag("plan") === true) {
planModeEnabled = true;
executionMode = false;
savedTools = pi.getActiveTools();
}
if (!savedTools) savedTools = pi.getActiveTools();
if (planModeEnabled) {
pi.setActiveTools(getPlanTools());
} else if (executionMode) {
restoreSavedTools();
}
updateUi(ctx);
});
}

11
.pi/agent/extensions/plan-mode/package.json Normal file
View file

@ -0,0 +1,11 @@
{
"name": "pi-plan-mode",
"private": true,
"version": "0.1.0",
"type": "module",
"pi": {
"extensions": [
"./index.ts"
]
}
}

152
.pi/agent/extensions/plan-mode/utils.ts Normal file
View file

@ -0,0 +1,152 @@
export interface TodoItem {
step: number;
text: string;
completed: boolean;
}
const DESTRUCTIVE_PATTERNS = [
/\brm\b/i,
/\brmdir\b/i,
/\bmv\b/i,
/\bcp\b/i,
/\bmkdir\b/i,
/\btouch\b/i,
/\bchmod\b/i,
/\bchown\b/i,
/\bchgrp\b/i,
/\bln\b/i,
/\btee\b/i,
/\btruncate\b/i,
/\bdd\b/i,
/\bshred\b/i,
/(^|[^<])>(?!>)/,
/>>/,
/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
/\byarn\s+(add|remove|install|publish)/i,
/\bpnpm\s+(add|remove|install|publish)/i,
/\bpip\s+(install|uninstall)/i,
/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
/\bbrew\s+(install|uninstall|upgrade)/i,
/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
/\bsudo\b/i,
/\bsu\b/i,
/\bkill\b/i,
/\bpkill\b/i,
/\bkillall\b/i,
/\breboot\b/i,
/\bshutdown\b/i,
/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
/\bservice\s+\S+\s+(start|stop|restart)/i,
/\b(vim?|nano|emacs|code|subl)\b/i,
];
const SAFE_PATTERNS = [
/^\s*cat\b/,
/^\s*head\b/,
/^\s*tail\b/,
/^\s*less\b/,
/^\s*more\b/,
/^\s*grep\b/,
/^\s*find\b/,
/^\s*ls\b/,
/^\s*pwd\b/,
/^\s*echo\b/,
/^\s*printf\b/,
/^\s*wc\b/,
/^\s*sort\b/,
/^\s*uniq\b/,
/^\s*diff\b/,
/^\s*file\b/,
/^\s*stat\b/,
/^\s*du\b/,
/^\s*df\b/,
/^\s*tree\b/,
/^\s*which\b/,
/^\s*whereis\b/,
/^\s*type\b/,
/^\s*env\b/,
/^\s*printenv\b/,
/^\s*uname\b/,
/^\s*whoami\b/,
/^\s*id\b/,
/^\s*date\b/,
/^\s*cal\b/,
/^\s*uptime\b/,
/^\s*ps\b/,
/^\s*top\b/,
/^\s*htop\b/,
/^\s*free\b/,
/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
/^\s*git\s+ls-/i,
/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
/^\s*yarn\s+(list|info|why|audit)/i,
/^\s*node\s+--version/i,
/^\s*python\s+--version/i,
/^\s*curl\s/i,
/^\s*wget\s+-O\s*-/i,
/^\s*jq\b/,
/^\s*sed\s+-n/i,
/^\s*awk\b/,
/^\s*rg\b/,
/^\s*fd\b/,
/^\s*bat\b/,
/^\s*exa\b/,
];
export function isSafeCommand(command: string): boolean {
const isDestructive = DESTRUCTIVE_PATTERNS.some((pattern) => pattern.test(command));
const isSafe = SAFE_PATTERNS.some((pattern) => pattern.test(command));
return !isDestructive && isSafe;
}
function cleanStepText(text: string): string {
let cleaned = text
.replace(/\*{1,2}([^*]+)\*{1,2}/g, "$1")
.replace(/`([^`]+)`/g, "$1")
.replace(/\s+/g, " ")
.trim();
if (cleaned.length > 0) cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
return cleaned;
}
export function extractTodoItems(message: string): TodoItem[] {
const items: TodoItem[] = [];
const headerMatch = message.match(/\*{0,2}Plan:\*{0,2}\s*\n/i);
if (!headerMatch) return items;
const planSection = message.slice(message.indexOf(headerMatch[0]) + headerMatch[0].length);
const numberedPattern = /^\s*(\d+)[.)]\s+(.+)$/gm;
for (const match of planSection.matchAll(numberedPattern)) {
const rawText = match[2]?.trim();
if (!rawText || rawText.startsWith("-") || rawText.startsWith("/")) continue;
const text = cleanStepText(rawText);
if (text.length < 4) continue;
items.push({
step: items.length + 1,
text,
completed: false,
});
}
return items;
}
export function extractDoneSteps(message: string): number[] {
const steps: number[] = [];
for (const match of message.matchAll(/\[DONE:(\d+)\]/gi)) {
const step = Number(match[1]);
if (Number.isFinite(step)) steps.push(step);
}
return steps;
}
export function markCompletedSteps(text: string, items: TodoItem[]): number {
const doneSteps = extractDoneSteps(text);
for (const step of doneSteps) {
const item = items.find((todo) => todo.step === step);
if (item) item.completed = true;
}
return doneSteps.length;
}

28
.pi/agent/extensions/subagent/README.md Normal file
View file

@ -0,0 +1,28 @@
# Subagent roles for pi
Installed roles:
- `reviewer` — review changes, bugs, risks, maintainability
- `librarian` — explore and map a codebase
- `uiux-designer` — UI/UX design direction, flows, states, and implementation guidance
## Commands
- `/subagents` — list discovered user-level agents
- `/subagents both` — include project-local `.pi/agents`
## Example prompts
- `Use the subagent tool with reviewer to inspect the auth refactor.`
- `Use subagent in parallel: librarian maps the settings flow, uiux-designer proposes an improved UX direction, reviewer lists product and implementation risks.`
- `Chain librarian -> uiux-designer to redesign onboarding. Use {previous} in the second task.`
## Notes
- User agents live in `~/.pi/agent/agents`
- Project-local agents can live in `.pi/agents`
- Project agents require `agentScope: "project"` or `"both"`
- Parallel mode allows up to 8 tasks and runs up to 4 concurrently
- `reviewer` uses `openai-codex/gpt-5.4:xhigh`
- `librarian` uses `anthropic/claude-sonnet-4-6`
- `uiux-designer` uses `google-antigravity/gemini-3.1-pro-high`

115
.pi/agent/extensions/subagent/agents.ts Normal file
View file

@ -0,0 +1,115 @@
import * as fs from "node:fs";
import * as path from "node:path";
import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
export type AgentScope = "user" | "project" | "both";
export interface AgentConfig {
name: string;
description: string;
tools?: string[];
model?: string;
systemPrompt: string;
source: "user" | "project";
filePath: string;
}
export interface AgentDiscoveryResult {
agents: AgentConfig[];
projectAgentsDir: string | null;
}
function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
const agents: AgentConfig[] = [];
if (!fs.existsSync(dir)) return agents;
let entries: fs.Dirent[];
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
return agents;
}
for (const entry of entries) {
if (!entry.name.endsWith(".md")) continue;
if (!entry.isFile() && !entry.isSymbolicLink()) continue;
const filePath = path.join(dir, entry.name);
let content: string;
try {
content = fs.readFileSync(filePath, "utf-8");
} catch {
continue;
}
const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
if (!frontmatter.name || !frontmatter.description) continue;
const tools = frontmatter.tools
?.split(",")
.map((t: string) => t.trim())
.filter(Boolean);
agents.push({
name: frontmatter.name,
description: frontmatter.description,
tools: tools && tools.length > 0 ? tools : undefined,
model: frontmatter.model,
systemPrompt: body,
source,
filePath,
});
}
return agents;
}
function isDirectory(p: string): boolean {
try {
return fs.statSync(p).isDirectory();
} catch {
return false;
}
}
function findNearestProjectAgentsDir(cwd: string): string | null {
let currentDir = cwd;
while (true) {
const candidate = path.join(currentDir, ".pi", "agents");
if (isDirectory(candidate)) return candidate;
const parentDir = path.dirname(currentDir);
if (parentDir === currentDir) return null;
currentDir = parentDir;
}
}
export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
const userDir = path.join(getAgentDir(), "agents");
const projectAgentsDir = findNearestProjectAgentsDir(cwd);
const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
const agentMap = new Map<string, AgentConfig>();
if (scope === "both") {
for (const agent of userAgents) agentMap.set(agent.name, agent);
for (const agent of projectAgents) agentMap.set(agent.name, agent);
} else if (scope === "user") {
for (const agent of userAgents) agentMap.set(agent.name, agent);
} else {
for (const agent of projectAgents) agentMap.set(agent.name, agent);
}
return { agents: Array.from(agentMap.values()), projectAgentsDir };
}
export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
if (agents.length === 0) return { text: "none", remaining: 0 };
const listed = agents.slice(0, maxItems);
const remaining = agents.length - listed.length;
return {
text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
remaining,
};
}

838
.pi/agent/extensions/subagent/index.ts Normal file
View file

@ -0,0 +1,838 @@
import { spawn } from "node:child_process";
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
import type { Message } from "@mariozechner/pi-ai";
import { StringEnum } from "@mariozechner/pi-ai";
import { type ExtensionAPI, getMarkdownTheme } from "@mariozechner/pi-coding-agent";
import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
import { Type } from "@sinclair/typebox";
import { type AgentConfig, type AgentScope, discoverAgents, formatAgentList } from "./agents.js";
const MAX_PARALLEL_TASKS = 8;
const MAX_CONCURRENCY = 4;
const COLLAPSED_ITEM_COUNT = 10;
interface UsageStats {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
cost: number;
contextTokens: number;
turns: number;
}
interface SingleResult {
agent: string;
agentSource: "user" | "project" | "unknown";
task: string;
exitCode: number;
messages: Message[];
stderr: string;
usage: UsageStats;
model?: string;
stopReason?: string;
errorMessage?: string;
step?: number;
}
interface SubagentDetails {
mode: "single" | "parallel" | "chain";
agentScope: AgentScope;
projectAgentsDir: string | null;
results: SingleResult[];
}
type ToolContent = Array<{ type: "text"; text: string }>;
type ToolUpdate = { content: ToolContent; details?: SubagentDetails; isError?: boolean };
type OnUpdateCallback = (partial: ToolUpdate) => void;
type DisplayItem = { type: "text"; text: string } | { type: "toolCall"; name: string; args: Record<string, any> };
function formatTokens(count: number): string {
if (count < 1000) return count.toString();
if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
if (count < 1000000) return `${Math.round(count / 1000)}k`;
return `${(count / 1000000).toFixed(1)}M`;
}
function formatUsageStats(
usage: {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
cost: number;
contextTokens?: number;
turns?: number;
},
model?: string,
): string {
const parts: string[] = [];
if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
if (model) parts.push(model);
return parts.join(" ");
}
function formatToolCall(
toolName: string,
args: Record<string, unknown>,
themeFg: (color: any, text: string) => string,
): string {
const shortenPath = (p: string) => {
const home = os.homedir();
return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
};
switch (toolName) {
case "bash": {
const command = (args.command as string) || "...";
const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
return themeFg("muted", "$ ") + themeFg("toolOutput", preview);
}
case "read": {
const rawPath = (args.file_path || args.path || "...") as string;
const filePath = shortenPath(rawPath);
const offset = args.offset as number | undefined;
const limit = args.limit as number | undefined;
let text = themeFg("accent", filePath);
if (offset !== undefined || limit !== undefined) {
const startLine = offset ?? 1;
const endLine = limit !== undefined ? startLine + limit - 1 : "";
text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
}
return themeFg("muted", "read ") + text;
}
case "write": {
const rawPath = (args.file_path || args.path || "...") as string;
const filePath = shortenPath(rawPath);
const content = (args.content || "") as string;
const lines = content.split("\n").length;
let text = themeFg("muted", "write ") + themeFg("accent", filePath);
if (lines > 1) text += themeFg("dim", ` (${lines} lines)`);
return text;
}
case "edit": {
const rawPath = (args.file_path || args.path || "...") as string;
return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
}
case "ls": {
const rawPath = (args.path || ".") as string;
return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
}
case "find": {
const pattern = (args.pattern || "*") as string;
const rawPath = (args.path || ".") as string;
return themeFg("muted", "find ") + themeFg("accent", pattern) + themeFg("dim", ` in ${shortenPath(rawPath)}`);
}
case "grep": {
const pattern = (args.pattern || "") as string;
const rawPath = (args.path || ".") as string;
return themeFg("muted", "grep ") + themeFg("accent", `/${pattern}/`) + themeFg("dim", ` in ${shortenPath(rawPath)}`);
}
default: {
const argsStr = JSON.stringify(args);
const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
return themeFg("accent", toolName) + themeFg("dim", ` ${preview}`);
}
}
}
function getFinalOutput(messages: Message[]): string {
for (let i = messages.length - 1; i >= 0; i--) {
const msg = messages[i];
if (msg.role === "assistant") {
for (const part of msg.content) {
if (part.type === "text") return part.text;
}
}
}
return "";
}
function getDisplayItems(messages: Message[]): DisplayItem[] {
const items: DisplayItem[] = [];
for (const msg of messages) {
if (msg.role === "assistant") {
for (const part of msg.content) {
if (part.type === "text") items.push({ type: "text", text: part.text });
else if (part.type === "toolCall") items.push({ type: "toolCall", name: part.name, args: part.arguments });
}
}
}
return items;
}
async function mapWithConcurrencyLimit<TIn, TOut>(
items: TIn[],
concurrency: number,
fn: (item: TIn, index: number) => Promise<TOut>,
): Promise<TOut[]> {
if (items.length === 0) return [];
const limit = Math.max(1, Math.min(concurrency, items.length));
const results: TOut[] = new Array(items.length);
let nextIndex = 0;
const workers = new Array(limit).fill(null).map(async () => {
while (true) {
const current = nextIndex++;
if (current >= items.length) return;
results[current] = await fn(items[current], current);
}
});
await Promise.all(workers);
return results;
}
function writePromptToTempFile(agentName: string, prompt: string): { dir: string; filePath: string } {
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
const safeName = agentName.replace(/[^\w.-]+/g, "_");
const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
fs.writeFileSync(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
return { dir: tmpDir, filePath };
}
async function runSingleAgent(
defaultCwd: string,
agents: AgentConfig[],
agentName: string,
task: string,
cwd: string | undefined,
step: number | undefined,
signal: AbortSignal | undefined,
onUpdate: OnUpdateCallback | undefined,
makeDetails: (results: SingleResult[]) => SubagentDetails,
): Promise<SingleResult> {
const agent = agents.find((a) => a.name === agentName);
if (!agent) {
const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
return {
agent: agentName,
agentSource: "unknown",
task,
exitCode: 1,
messages: [],
stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
step,
};
}
const args: string[] = ["--mode", "json", "-p", "--no-session"];
if (agent.model) args.push("--model", agent.model);
if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
let tmpPromptDir: string | null = null;
let tmpPromptPath: string | null = null;
const currentResult: SingleResult = {
agent: agentName,
agentSource: agent.source,
task,
exitCode: 0,
messages: [],
stderr: "",
usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
model: agent.model,
step,
};
const emitUpdate = () => {
if (!onUpdate) return;
onUpdate({
content: [{ type: "text", text: getFinalOutput(currentResult.messages) || "(running...)" }],
details: makeDetails([currentResult]),
});
};
try {
if (agent.systemPrompt.trim()) {
const tmp = writePromptToTempFile(agent.name, agent.systemPrompt);
tmpPromptDir = tmp.dir;
tmpPromptPath = tmp.filePath;
args.push("--append-system-prompt", tmpPromptPath);
}
args.push(`Task: ${task}`);
let wasAborted = false;
const exitCode = await new Promise<number>((resolve) => {
const proc = spawn("pi", args, { cwd: cwd ?? defaultCwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
let buffer = "";
const processLine = (line: string) => {
if (!line.trim()) return;
let event: any;
try {
event = JSON.parse(line);
} catch {
return;
}
if (event.type === "message_end" && event.message) {
const msg = event.message as Message;
currentResult.messages.push(msg);
if (msg.role === "assistant") {
currentResult.usage.turns++;
const usage = msg.usage;
if (usage) {
currentResult.usage.input += usage.input || 0;
currentResult.usage.output += usage.output || 0;
currentResult.usage.cacheRead += usage.cacheRead || 0;
currentResult.usage.cacheWrite += usage.cacheWrite || 0;
currentResult.usage.cost += usage.cost?.total || 0;
currentResult.usage.contextTokens = usage.totalTokens || 0;
}
if (!currentResult.model && msg.model) currentResult.model = msg.model;
if (msg.stopReason) currentResult.stopReason = msg.stopReason;
if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
}
emitUpdate();
}
if (event.type === "tool_result_end" && event.message) {
currentResult.messages.push(event.message as Message);
emitUpdate();
}
};
proc.stdout.on("data", (data) => {
buffer += data.toString();
const lines = buffer.split("\n");
buffer = lines.pop() || "";
for (const line of lines) processLine(line);
});
proc.stderr.on("data", (data) => {
currentResult.stderr += data.toString();
});
proc.on("close", (code) => {
if (buffer.trim()) processLine(buffer);
resolve(code ?? 0);
});
proc.on("error", () => resolve(1));
if (signal) {
const killProc = () => {
wasAborted = true;
proc.kill("SIGTERM");
setTimeout(() => {
if (!proc.killed) proc.kill("SIGKILL");
}, 5000);
};
if (signal.aborted) killProc();
else signal.addEventListener("abort", killProc, { once: true });
}
});
currentResult.exitCode = exitCode;
if (wasAborted) throw new Error("Subagent was aborted");
return currentResult;
} finally {
if (tmpPromptPath) {
try {
fs.unlinkSync(tmpPromptPath);
} catch {}
}
if (tmpPromptDir) {
try {
fs.rmdirSync(tmpPromptDir);
} catch {}
}
}
}
const TaskItem = Type.Object({
agent: Type.String({ description: "Name of the agent to invoke" }),
task: Type.String({ description: "Task to delegate to the agent" }),
cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
});
const ChainItem = Type.Object({
agent: Type.String({ description: "Name of the agent to invoke" }),
task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
});
const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
description: 'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
default: "user",
});
const SubagentParams = Type.Object({
agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (single mode)" })),
task: Type.Optional(Type.String({ description: "Task to delegate (single mode)" })),
tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
chain: Type.Optional(Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" })),
agentScope: Type.Optional(AgentScopeSchema),
confirmProjectAgents: Type.Optional(
Type.Boolean({ description: "Prompt before running project-local agents. Default: true.", default: true }),
),
cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
});
export default function (pi: ExtensionAPI) {
pi.registerCommand("subagents", {
description: "List discovered subagent roles",
handler: async (args, ctx) => {
const requestedScope = (args.trim() as AgentScope) || "user";
const scope: AgentScope = ["user", "project", "both"].includes(requestedScope) ? requestedScope : "user";
const discovery = discoverAgents(ctx.cwd, scope);
const list = discovery.agents.map((agent) => `- ${agent.name} (${agent.source}): ${agent.description}`).join("\n");
ctx.ui.notify(list || `No agents found for scope: ${scope}`, "info");
},
});
pi.registerTool({
name: "subagent",
label: "Subagent",
description: [
"Delegate work to specialized subagents with isolated context.",
"Supports single, parallel, and chained execution.",
"Useful built-in roles: reviewer, librarian, uiux-designer.",
'Default scope is "user" (~/.pi/agent/agents). Set agentScope to "both" or "project" to include repo-local agents.',
].join(" "),
parameters: SubagentParams,
async execute(_toolCallId, params, signal, onUpdate, ctx) {
const agentScope: AgentScope = params.agentScope ?? "user";
const discovery = discoverAgents(ctx.cwd, agentScope);
const agents = discovery.agents;
const confirmProjectAgents = params.confirmProjectAgents ?? true;
const availableAgents = formatAgentList(agents, 8);
const hasChain = (params.chain?.length ?? 0) > 0;
const hasTasks = (params.tasks?.length ?? 0) > 0;
const hasSingle = Boolean(params.agent && params.task);
const modeCount = Number(hasChain) + Number(hasTasks) + Number(hasSingle);
const makeDetails =
(mode: "single" | "parallel" | "chain") =>
(results: SingleResult[]): SubagentDetails => ({
mode,
agentScope,
projectAgentsDir: discovery.projectAgentsDir,
results,
});
if (modeCount !== 1) {
return {
content: [{ type: "text", text: `Invalid parameters. Available agents: ${availableAgents.text}` }],
details: makeDetails("single")([]),
};
}
if ((agentScope === "project" || agentScope === "both") && confirmProjectAgents && ctx.hasUI) {
const requestedAgentNames = new Set<string>();
if (params.chain) for (const step of params.chain) requestedAgentNames.add(step.agent);
if (params.tasks) for (const task of params.tasks) requestedAgentNames.add(task.agent);
if (params.agent) requestedAgentNames.add(params.agent);
const projectAgentsRequested = Array.from(requestedAgentNames)
.map((name) => agents.find((a) => a.name === name))
.filter((agent): agent is AgentConfig => agent?.source === "project");
if (projectAgentsRequested.length > 0) {
const names = projectAgentsRequested.map((a) => a.name).join(", ");
const dir = discovery.projectAgentsDir ?? "(unknown)";
const ok = await ctx.ui.confirm(
"Run project-local agents?",
`Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Continue only for trusted repositories.`,
);
if (!ok) {
return {
content: [{ type: "text", text: "Canceled: project-local agents were not approved." }],
details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
};
}
}
}
if (params.chain && params.chain.length > 0) {
const results: SingleResult[] = [];
let previousOutput = "";
for (let i = 0; i < params.chain.length; i++) {
const step = params.chain[i];
const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
const chainUpdate: OnUpdateCallback | undefined = onUpdate
? (partial) => {
const currentResult = partial.details?.results[0];
if (!currentResult) return;
onUpdate({
content: partial.content,
details: makeDetails("chain")([...results, currentResult]),
});
}
: undefined;
const result = await runSingleAgent(
ctx.cwd,
agents,
step.agent,
taskWithContext,
step.cwd,
i + 1,
signal,
chainUpdate,
makeDetails("chain"),
);
results.push(result);
const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
if (isError) {
const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
return {
content: [{ type: "text", text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}` }],
details: makeDetails("chain")(results),
isError: true,
};
}
previousOutput = getFinalOutput(result.messages);
}
return {
content: [{ type: "text", text: getFinalOutput(results[results.length - 1].messages) || "(no output)" }],
details: makeDetails("chain")(results),
};
}
if (params.tasks && params.tasks.length > 0) {
if (params.tasks.length > MAX_PARALLEL_TASKS) {
return {
content: [{ type: "text", text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.` }],
details: makeDetails("parallel")([]),
};
}
const allResults: SingleResult[] = new Array(params.tasks.length);
for (let i = 0; i < params.tasks.length; i++) {
allResults[i] = {
agent: params.tasks[i].agent,
agentSource: "unknown",
task: params.tasks[i].task,
exitCode: -1,
messages: [],
stderr: "",
usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
};
}
const emitParallelUpdate = () => {
if (!onUpdate) return;
const running = allResults.filter((r) => r.exitCode === -1).length;
const done = allResults.filter((r) => r.exitCode !== -1).length;
onUpdate({
content: [{ type: "text", text: `Parallel: ${done}/${allResults.length} done, ${running} running...` }],
details: makeDetails("parallel")([...allResults]),
});
};
const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (task, index) => {
const result = await runSingleAgent(
ctx.cwd,
agents,
task.agent,
task.task,
task.cwd,
undefined,
signal,
(partial) => {
if (partial.details?.results[0]) {
allResults[index] = partial.details.results[0];
emitParallelUpdate();
}
},
makeDetails("parallel"),
);
allResults[index] = result;
emitParallelUpdate();
return result;
});
const successCount = results.filter((r) => r.exitCode === 0).length;
const summaries = results.map((r) => {
const output = getFinalOutput(r.messages);
const preview = output.slice(0, 100) + (output.length > 100 ? "..." : "");
return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}: ${preview || "(no output)"}`;
});
return {
content: [{ type: "text", text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n")}` }],
details: makeDetails("parallel")(results),
};
}
if (params.agent && params.task) {
const result = await runSingleAgent(
ctx.cwd,
agents,
params.agent,
params.task,
params.cwd,
undefined,
signal,
onUpdate as OnUpdateCallback | undefined,
makeDetails("single"),
);
const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
if (isError) {
const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
return {
content: [{ type: "text", text: `Agent ${result.stopReason || "failed"}: ${errorMsg}` }],
details: makeDetails("single")([result]),
isError: true,
};
}
return {
content: [{ type: "text", text: getFinalOutput(result.messages) || "(no output)" }],
details: makeDetails("single")([result]),
};
}
return {
content: [{ type: "text", text: `Invalid parameters. Available agents: ${availableAgents.text}` }],
details: makeDetails("single")([]),
};
},
renderCall(args, theme) {
const scope: AgentScope = args.agentScope ?? "user";
if (args.chain && args.chain.length > 0) {
let text =
theme.fg("toolTitle", theme.bold("subagent ")) +
theme.fg("accent", `chain (${args.chain.length} steps)`) +
theme.fg("muted", ` [${scope}]`);
for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
const step = args.chain[i];
const cleanTask = step.task.replace(/\{previous\}/g, "").trim();
const preview = cleanTask.length > 40 ? `${cleanTask.slice(0, 40)}...` : cleanTask;
text += `\n ${theme.fg("muted", `${i + 1}.`)} ${theme.fg("accent", step.agent)}${theme.fg("dim", ` ${preview}`)}`;
}
if (args.chain.length > 3) text += `\n ${theme.fg("muted", `... +${args.chain.length - 3} more`)}`;
return new Text(text, 0, 0);
}
if (args.tasks && args.tasks.length > 0) {
let text =
theme.fg("toolTitle", theme.bold("subagent ")) +
theme.fg("accent", `parallel (${args.tasks.length} tasks)`) +
theme.fg("muted", ` [${scope}]`);
for (const task of args.tasks.slice(0, 3)) {
const preview = task.task.length > 40 ? `${task.task.slice(0, 40)}...` : task.task;
text += `\n ${theme.fg("accent", task.agent)}${theme.fg("dim", ` ${preview}`)}`;
}
if (args.tasks.length > 3) text += `\n ${theme.fg("muted", `... +${args.tasks.length - 3} more`)}`;
return new Text(text, 0, 0);
}
const agentName = args.agent || "...";
const preview = args.task ? (args.task.length > 60 ? `${args.task.slice(0, 60)}...` : args.task) : "...";
let text = theme.fg("toolTitle", theme.bold("subagent ")) + theme.fg("accent", agentName) + theme.fg("muted", ` [${scope}]`);
text += `\n ${theme.fg("dim", preview)}`;
return new Text(text, 0, 0);
},
renderResult(result, { expanded }, theme) {
const details = result.details as SubagentDetails | undefined;
if (!details || details.results.length === 0) {
const text = result.content[0];
return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
}
const mdTheme = getMarkdownTheme();
const renderDisplayItems = (items: DisplayItem[], limit?: number) => {
const toShow = limit ? items.slice(-limit) : items;
const skipped = limit && items.length > limit ? items.length - limit : 0;
let text = "";
if (skipped > 0) text += theme.fg("muted", `... ${skipped} earlier items\n`);
for (const item of toShow) {
if (item.type === "text") {
const preview = expanded ? item.text : item.text.split("\n").slice(0, 3).join("\n");
text += `${theme.fg("toolOutput", preview)}\n`;
} else {
text += `${theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`;
}
}
return text.trimEnd();
};
const aggregateUsage = (results: SingleResult[]) => {
const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
for (const item of results) {
total.input += item.usage.input;
total.output += item.usage.output;
total.cacheRead += item.usage.cacheRead;
total.cacheWrite += item.usage.cacheWrite;
total.cost += item.usage.cost;
total.turns += item.usage.turns;
}
return total;
};
if (details.mode === "single" && details.results.length === 1) {
const item = details.results[0];
const isError = item.exitCode !== 0 || item.stopReason === "error" || item.stopReason === "aborted";
const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
const displayItems = getDisplayItems(item.messages);
const finalOutput = getFinalOutput(item.messages);
if (expanded) {
const container = new Container();
let header = `${icon} ${theme.fg("toolTitle", theme.bold(item.agent))}${theme.fg("muted", ` (${item.agentSource})`)}`;
if (isError && item.stopReason) header += ` ${theme.fg("error", `[${item.stopReason}]`)}`;
container.addChild(new Text(header, 0, 0));
if (isError && item.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${item.errorMessage}`), 0, 0));
container.addChild(new Spacer(1));
container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
container.addChild(new Text(theme.fg("dim", item.task), 0, 0));
container.addChild(new Spacer(1));
container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
if (displayItems.length === 0 && !finalOutput) {
container.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
} else {
for (const displayItem of displayItems) {
if (displayItem.type === "toolCall") {
container.addChild(new Text(theme.fg("muted", "→ ") + formatToolCall(displayItem.name, displayItem.args, theme.fg.bind(theme)), 0, 0));
}
}
if (finalOutput) {
container.addChild(new Spacer(1));
container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
}
}
const usageStr = formatUsageStats(item.usage, item.model);
if (usageStr) {
container.addChild(new Spacer(1));
container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
}
return container;
}
let text = `${icon} ${theme.fg("toolTitle", theme.bold(item.agent))}${theme.fg("muted", ` (${item.agentSource})`)}`;
if (isError && item.stopReason) text += ` ${theme.fg("error", `[${item.stopReason}]`)}`;
if (isError && item.errorMessage) text += `\n${theme.fg("error", `Error: ${item.errorMessage}`)}`;
else if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
else {
text += `\n${renderDisplayItems(displayItems, COLLAPSED_ITEM_COUNT)}`;
if (displayItems.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
}
const usageStr = formatUsageStats(item.usage, item.model);
if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
return new Text(text, 0, 0);
}
if (details.mode === "chain") {
const successCount = details.results.filter((r) => r.exitCode === 0).length;
const icon = successCount === details.results.length ? theme.fg("success", "✓") : theme.fg("error", "✗");
if (expanded) {
const container = new Container();
container.addChild(new Text(icon + " " + theme.fg("toolTitle", theme.bold("chain ")) + theme.fg("accent", `${successCount}/${details.results.length} steps`), 0, 0));
for (const item of details.results) {
const itemIcon = item.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
const displayItems = getDisplayItems(item.messages);
const finalOutput = getFinalOutput(item.messages);
container.addChild(new Spacer(1));
container.addChild(new Text(`${theme.fg("muted", `─── Step ${item.step}: `)}${theme.fg("accent", item.agent)} ${itemIcon}`, 0, 0));
container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", item.task), 0, 0));
for (const displayItem of displayItems) {
if (displayItem.type === "toolCall") {
container.addChild(new Text(theme.fg("muted", "→ ") + formatToolCall(displayItem.name, displayItem.args, theme.fg.bind(theme)), 0, 0));
}
}
if (finalOutput) {
container.addChild(new Spacer(1));
container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
}
const usageStr = formatUsageStats(item.usage, item.model);
if (usageStr) container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
}
const totalUsageStr = formatUsageStats(aggregateUsage(details.results));
if (totalUsageStr) {
container.addChild(new Spacer(1));
container.addChild(new Text(theme.fg("dim", `Total: ${totalUsageStr}`), 0, 0));
}
return container;
}
let text = icon + " " + theme.fg("toolTitle", theme.bold("chain ")) + theme.fg("accent", `${successCount}/${details.results.length} steps`);
for (const item of details.results) {
const itemIcon = item.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
const displayItems = getDisplayItems(item.messages);
text += `\n\n${theme.fg("muted", `─── Step ${item.step}: `)}${theme.fg("accent", item.agent)} ${itemIcon}`;
if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
else text += `\n${renderDisplayItems(displayItems, 5)}`;
}
const totalUsageStr = formatUsageStats(aggregateUsage(details.results));
if (totalUsageStr) text += `\n\n${theme.fg("dim", `Total: ${totalUsageStr}`)}`;
text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
return new Text(text, 0, 0);
}
if (details.mode === "parallel") {
const running = details.results.filter((r) => r.exitCode === -1).length;
const successCount = details.results.filter((r) => r.exitCode === 0).length;
const failCount = details.results.filter((r) => r.exitCode > 0).length;
const isRunning = running > 0;
const icon = isRunning ? theme.fg("warning", "⏳") : failCount > 0 ? theme.fg("warning", "◐") : theme.fg("success", "✓");
const status = isRunning ? `${successCount + failCount}/${details.results.length} done, ${running} running` : `${successCount}/${details.results.length} tasks`;
if (expanded && !isRunning) {
const container = new Container();
container.addChild(new Text(`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`, 0, 0));
for (const item of details.results) {
const itemIcon = item.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
const displayItems = getDisplayItems(item.messages);
const finalOutput = getFinalOutput(item.messages);
container.addChild(new Spacer(1));
container.addChild(new Text(`${theme.fg("muted", "─── ")}${theme.fg("accent", item.agent)} ${itemIcon}`, 0, 0));
container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", item.task), 0, 0));
for (const displayItem of displayItems) {
if (displayItem.type === "toolCall") {
container.addChild(new Text(theme.fg("muted", "→ ") + formatToolCall(displayItem.name, displayItem.args, theme.fg.bind(theme)), 0, 0));
}
}
if (finalOutput) {
container.addChild(new Spacer(1));
container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
}
const usageStr = formatUsageStats(item.usage, item.model);
if (usageStr) container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
}
const totalUsageStr = formatUsageStats(aggregateUsage(details.results));
if (totalUsageStr) {
container.addChild(new Spacer(1));
container.addChild(new Text(theme.fg("dim", `Total: ${totalUsageStr}`), 0, 0));
}
return container;
}
let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`;
for (const item of details.results) {
const itemIcon = item.exitCode === -1 ? theme.fg("warning", "⏳") : item.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
const displayItems = getDisplayItems(item.messages);
text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", item.agent)} ${itemIcon}`;
if (displayItems.length === 0) text += `\n${theme.fg("muted", item.exitCode === -1 ? "(running...)" : "(no output)")}`;
else text += `\n${renderDisplayItems(displayItems, 5)}`;
}
if (!isRunning) {
const totalUsageStr = formatUsageStats(aggregateUsage(details.results));
if (totalUsageStr) text += `\n\n${theme.fg("dim", `Total: ${totalUsageStr}`)}`;
}
if (!expanded) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
return new Text(text, 0, 0);
}
const text = result.content[0];
return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
},
});
}

11
.pi/agent/extensions/subagent/package.json Normal file
View file

@ -0,0 +1,11 @@
{
"name": "pi-subagent-roles",
"private": true,
"version": "0.1.0",
"type": "module",
"pi": {
"extensions": [
"./index.ts"
]
}
}

7
.pi/agent/settings.json Normal file
View file

@ -0,0 +1,7 @@
{
"lastChangelogVersion": "0.57.1",
"defaultProvider": "anthropic",
"defaultModel": "claude-opus-4-6",
"defaultThinkingLevel": "high",
"theme": "catppuccin-mocha"
}

96
.pi/agent/themes/catppuccin-mocha.json Normal file
View file

@ -0,0 +1,96 @@
{
"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
"name": "catppuccin-mocha",
"vars": {
"rosewater": "#f5e0dc",
"flamingo": "#f2cdcd",
"pink": "#f5c2e7",
"mauve": "#cba6f7",
"red": "#f38ba8",
"maroon": "#eba0ac",
"peach": "#fab387",
"yellow": "#f9e2af",
"green": "#a6e3a1",
"teal": "#94e2d5",
"sky": "#89dceb",
"sapphire": "#74c7ec",
"blue": "#89b4fa",
"lavender": "#b4befe",
"text": "#cdd6f4",
"subtext1": "#bac2de",
"subtext0": "#a6adc8",
"overlay2": "#9399b2",
"overlay1": "#7f849c",
"overlay0": "#6c7086",
"surface2": "#585b70",
"surface1": "#45475a",
"surface0": "#313244",
"base": "#1e1e2e",
"mantle": "#181825",
"crust": "#11111b"
},
"colors": {
"accent": "mauve",
"border": "surface1",
"borderAccent": "lavender",
"borderMuted": "surface0",
"success": "green",
"error": "red",
"warning": "yellow",
"muted": "subtext1",
"dim": "overlay0",
"text": "text",
"thinkingText": "subtext0",
"selectedBg": "surface0",
"userMessageBg": "mantle",
"userMessageText": "text",
"customMessageBg": "surface0",
"customMessageText": "text",
"customMessageLabel": "mauve",
"toolPendingBg": "mantle",
"toolSuccessBg": "surface0",
"toolErrorBg": "surface0",
"toolTitle": "lavender",
"toolOutput": "subtext1",
"mdHeading": "lavender",
"mdLink": "blue",
"mdLinkUrl": "subtext0",
"mdCode": "teal",
"mdCodeBlock": "green",
"mdCodeBlockBorder": "surface1",
"mdQuote": "subtext0",
"mdQuoteBorder": "surface1",
"mdHr": "surface1",
"mdListBullet": "mauve",
"toolDiffAdded": "green",
"toolDiffRemoved": "red",
"toolDiffContext": "subtext0",
"syntaxComment": "overlay1",
"syntaxKeyword": "mauve",
"syntaxFunction": "blue",
"syntaxVariable": "text",
"syntaxString": "green",
"syntaxNumber": "peach",
"syntaxType": "yellow",
"syntaxOperator": "sky",
"syntaxPunctuation": "subtext1",
"thinkingOff": "surface0",
"thinkingMinimal": "overlay0",
"thinkingLow": "blue",
"thinkingMedium": "teal",
"thinkingHigh": "mauve",
"thinkingXhigh": "red",
"bashMode": "green"
},
"export": {
"pageBg": "#11111b",
"cardBg": "#1e1e2e",
"infoBg": "#313244"
}
}