@tintinweb/pi-subagents 0.2.2 → 0.2.5

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.5] - 2026-03-06
+
+### Added
+- **Interactive `/agents` menu** — single command replaces `/agent` and `/agents` with a full management wizard
+  - Browse and manage running agents
+  - Custom agents submenu — edit or delete existing agents
+  - Create new custom agents via manual wizard or AI-generated (with comprehensive frontmatter documentation for the generator)
+  - Settings: configure max concurrency, default max turns, and grace turns at runtime
+  - Built-in agent types shown with model info (e.g. `Explore · haiku`)
+  - Aligned formatting for agent lists
+- **Configurable turn limits** — `defaultMaxTurns` and `graceTurns` are now runtime-adjustable via `/agents` → Settings
+- Sub-menus return to main menu instead of exiting
+
+### Removed
+- `/agent <type> <prompt>` command (use `Agent` tool directly, or create custom agents via `/agents`)
+
+## [0.2.4] - 2026-03-06
+
+### Added
+- **Global custom agents** — agents in `~/.pi/agent/agents/*.md` are now discovered automatically and available across all projects
+- Two-tier discovery hierarchy: project-level (`.pi/agents/`) overrides global (`~/.pi/agent/agents/`)
+
+## [0.2.3] - 2026-03-05
+
+### Added
+- Screenshot in README
+
 ## [0.2.2] - 2026-03-05
 
 ### Changed
@@ -77,6 +104,9 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.2.5]: https://github.com/tintinweb/pi-subagents/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/tintinweb/pi-subagents/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/tintinweb/pi-subagents/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/tintinweb/pi-subagents/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/tintinweb/pi-subagents/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/tintinweb/pi-subagents/compare/v0.1.0...v0.2.0

package/README.md

@@ -4,6 +4,12 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 
 > **Status:** Early release.
 
+<img width="600" alt="pi-subagents screenshot" src="https://github.com/tintinweb/pi-subagents/raw/master/media/screenshot.png" />
+
+
+https://github.com/user-attachments/assets/5d1331e8-6d02-420b-b30a-dcbf838b1660
+
+
 ## Features
 
 - **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `get_subagent_result`, `steer_subagent`) — feels native
@@ -81,7 +87,16 @@ Completed results can be expanded (ctrl+o in pi) to show the full agent output i
 
 ## Custom Agents
 
-Define custom agent types by creating `.pi/agents/<name>.md` files. The filename becomes the agent type name.
+Define custom agent types by creating `.md` files. The filename becomes the agent type name.
+
+Custom agents are discovered from two locations (higher priority wins):
+
+| Priority | Location | Scope |
+|----------|----------|-------|
+| 1 (highest) | `.pi/agents/<name>.md` | Project — per-repo agents |
+| 2 | `~/.pi/agent/agents/<name>.md` | Global — available everywhere |
+
+Project-level agents override global ones with the same name, so you can customize a global agent for a specific project.
 
 ### Example: `.pi/agents/auditor.md`
 
@@ -171,15 +186,27 @@ Send a steering message to a running agent. The message interrupts after the cur
 
 | Command | Description |
 |---------|-------------|
-| `/agent <type> <prompt>` | Spawn a sub-agent interactively |
-| `/agents` | List all agents with status tree |
+| `/agents` | Interactive agent management menu |
+
+The `/agents` command opens an interactive menu:
 
 ```
-/agent Explore Find all TypeScript files that handle authentication
-/agent Plan Design a caching layer for the API
-/agent auditor Review the payment processing module
+Running agents (2) — 1 running, 1 done     ← only shown when agents exist
+Custom agents (3)                           ← submenu: edit or delete agents
+Create new agent                            ← manual wizard or AI-generated
+Settings                                    ← max concurrency, max turns, grace turns
+
+Built-in (always available):
+  general-purpose · inherit
+  Explore         · haiku
+  Plan            · inherit
+  ...
 ```
 
+- **Custom agents submenu** — select an agent to edit (opens editor) or delete
+- **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do and a sub-agent writes the `.md` file)
+- **Settings** — configure max concurrency, default max turns, and grace turns at runtime
+
 ## Graceful Max Turns
 
 Instead of hard-aborting at the turn limit, agents get a graceful shutdown:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "A pi extension providing autonomous sub-agents with Claude Code-style UI",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-runner.ts

@@ -23,10 +23,20 @@ import type { SubagentType, ThinkingLevel } from "./types.js";
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 
 /** Default max turns to prevent subagents from looping indefinitely. */
-const DEFAULT_MAX_TURNS = 50;
+let defaultMaxTurns = 50;
+
+/** Get the default max turns value. */
+export function getDefaultMaxTurns(): number { return defaultMaxTurns; }
+/** Set the default max turns value (minimum 1). */
+export function setDefaultMaxTurns(n: number): void { defaultMaxTurns = Math.max(1, n); }
 
 /** Additional turns allowed after the soft limit steer message. */
-const GRACE_TURNS = 5;
+let graceTurns = 5;
+
+/** Get the grace turns value. */
+export function getGraceTurns(): number { return graceTurns; }
+/** Set the grace turns value (minimum 1). */
+export function setGraceTurns(n: number): void { graceTurns = Math.max(1, n); }
 
 /** Haiku model IDs to try for Explore agents (in preference order). */
 const HAIKU_MODEL_IDS = [
@@ -215,7 +225,7 @@ export async function runAgent(
 
   // Track turns for graceful max_turns enforcement
   let turnCount = 0;
-  const maxTurns = options.maxTurns ?? customConfig?.maxTurns ?? DEFAULT_MAX_TURNS;
+  const maxTurns = options.maxTurns ?? customConfig?.maxTurns ?? defaultMaxTurns;
   let softLimitReached = false;
   let aborted = false;
 
@@ -226,7 +236,7 @@ export async function runAgent(
       if (!softLimitReached && turnCount >= maxTurns) {
         softLimitReached = true;
         session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
-      } else if (softLimitReached && turnCount >= maxTurns + GRACE_TURNS) {
+      } else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
         aborted = true;
         session.abort();
       }

package/src/custom-agents.ts

@@ -1,30 +1,43 @@
 /**
- * custom-agents.ts — Load user-defined agents from .pi/agents/*.md files.
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global (~/.pi/agent/agents/) locations.
  */
 
 import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
+import { homedir } from "node:os";
 import { SUBAGENT_TYPES, type CustomAgentConfig, type ThinkingLevel } from "./types.js";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 
 /**
- * Scan .pi/agents/*.md and return a map of custom agent configs.
- * Filename (without .md) becomes the agent name.
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project: <cwd>/.pi/agents/*.md
+ *   2. Global:  ~/.pi/agent/agents/*.md
+ *
+ * Project-level agents override global ones with the same name.
  */
 export function loadCustomAgents(cwd: string): Map<string, CustomAgentConfig> {
-  const dir = join(cwd, ".pi", "agents");
-  if (!existsSync(dir)) return new Map();
+  const globalDir = join(homedir(), ".pi", "agent", "agents");
+  const projectDir = join(cwd, ".pi", "agents");
+
+  const agents = new Map<string, CustomAgentConfig>();
+  loadFromDir(globalDir, agents);   // lower priority
+  loadFromDir(projectDir, agents);  // higher priority (overwrites)
+  return agents;
+}
+
+/** Load agent configs from a directory into the map. */
+function loadFromDir(dir: string, agents: Map<string, CustomAgentConfig>): void {
+  if (!existsSync(dir)) return;
 
   let files: string[];
   try {
     files = readdirSync(dir).filter(f => f.endsWith(".md"));
   } catch {
-    return new Map();
+    return;
   }
 
-  const agents = new Map<string, CustomAgentConfig>();
-
   for (const file of files) {
     const name = basename(file, ".md");
     if ((SUBAGENT_TYPES as readonly string[]).includes(name)) continue;
@@ -54,8 +67,6 @@ export function loadCustomAgents(cwd: string): Map<string, CustomAgentConfig> {
       isolated: fm.isolated === true,
     });
   }
-
-  return agents;
 }
 
 // ---- Field parsers ----

package/src/index.ts

@@ -7,17 +7,19 @@
  *   steer_subagent       — LLM-callable: send a steering message to a running agent
  *
  * Commands:
- *   /agent <type> <prompt>  — User-invocable agent spawning
- *   /agents                 — List all agents with status
+ *   /agents                 — Interactive agent management menu
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { existsSync, mkdirSync, unlinkSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { steerAgent, getAgentConversation } from "./agent-runner.js";
+import { steerAgent, getAgentConversation, getDefaultMaxTurns, setDefaultMaxTurns, getGraceTurns, setGraceTurns } from "./agent-runner.js";
 import { SUBAGENT_TYPES, type SubagentType, type ThinkingLevel, type CustomAgentConfig } from "./types.js";
-import { getConfig, getAvailableTypes, getCustomAgentNames, getCustomAgentConfig, isValidType, registerCustomAgents } from "./agent-types.js";
+import { getAvailableTypes, getCustomAgentNames, getCustomAgentConfig, isValidType, registerCustomAgents, BUILTIN_TOOL_NAMES } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import {
   AgentWidget,
@@ -256,7 +258,7 @@ export default function (pi: ExtensionAPI) {
       ...builtinDescs,
       ...(customDescs.length > 0 ? ["", "Custom types:", ...customDescs] : []),
       "",
-      "Custom agents can be defined in .pi/agents/<name>.md — they are picked up automatically.",
+      "Custom agents can be defined in .pi/agents/<name>.md (project) or ~/.pi/agent/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones.",
     ].join("\n");
   };
 
@@ -295,7 +297,7 @@ Guidelines:
         description: "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Built-in: ${SUBAGENT_TYPES.join(", ")}. Custom agents from .pi/agents/*.md are also available.`,
+        description: `The type of specialized agent to use. Built-in: ${SUBAGENT_TYPES.join(", ")}. Custom agents from .pi/agents/*.md (project) or ~/.pi/agent/agents/*.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -717,139 +719,418 @@ Guidelines:
     },
   });
 
-  // ---- /agent command ----
-
-  pi.registerCommand("agent", {
-    description: "Spawn a sub-agent: /agent <type> <prompt>",
-    handler: async (args, ctx) => {
-      const trimmed = args?.trim() ?? "";
-
-      if (!trimmed) {
-        const lines = [
-          "Usage: /agent <type> <prompt>",
-          "",
-          "Agent types:",
-          ...getAvailableTypes().map(
-            (t) => `  ${t.padEnd(20)} ${getConfig(t).description}`,
-          ),
-          "",
-          "Examples:",
-          "  /agent Explore Find all TypeScript files that handle authentication",
-          "  /agent Plan Design a caching layer for the API",
-          "  /agent general-purpose Refactor the auth module to use JWT",
-        ];
-        ctx.ui.notify(lines.join("\n"), "info");
-        return;
-      }
+  // ---- /agents interactive menu ----
 
-      // Parse: first word is type, rest is prompt
-      const spaceIdx = trimmed.indexOf(" ");
-      if (spaceIdx === -1) {
-        ctx.ui.notify(
-          `Missing prompt. Usage: /agent <type> <prompt>\nTypes: ${getAvailableTypes().join(", ")}`,
-          "warning",
-        );
-        return;
-      }
+  const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
+  const personalAgentsDir = () => join(homedir(), ".pi", "agent", "agents");
 
-      const typeName = trimmed.slice(0, spaceIdx);
-      const prompt = trimmed.slice(spaceIdx + 1).trim();
+  /** Find the file path of a custom agent by name (project first, then global). */
+  function findAgentFile(name: string): { path: string; location: "project" | "personal" } | undefined {
+    const projectPath = join(projectAgentsDir(), `${name}.md`);
+    if (existsSync(projectPath)) return { path: projectPath, location: "project" };
+    const personalPath = join(personalAgentsDir(), `${name}.md`);
+    if (existsSync(personalPath)) return { path: personalPath, location: "personal" };
+    return undefined;
+  }
 
-      if (!isValidType(typeName)) {
-        ctx.ui.notify(
-          `Unknown agent type: "${typeName}"\nValid types: ${getAvailableTypes().join(", ")}`,
-          "warning",
-        );
-        return;
-      }
+  /** Model label for display: built-in types have known defaults, custom agents show their config. */
+  const BUILTIN_MODEL_LABELS: Record<string, string> = {
+    "general-purpose": "inherit",
+    "Explore": "haiku",
+    "Plan": "inherit",
+    "statusline-setup": "inherit",
+    "claude-code-guide": "inherit",
+  };
 
-      if (!prompt) {
-        ctx.ui.notify("Missing prompt.", "warning");
-        return;
-      }
+  function getModelLabel(type: string): string {
+    const builtin = BUILTIN_MODEL_LABELS[type];
+    if (builtin) return builtin;
+    const custom = getCustomAgentConfig(type);
+    if (custom?.model) {
+      // Show short form: "anthropic/claude-haiku-4-5-20251001" → "haiku"
+      const id = custom.model.toLowerCase();
+      if (id.includes("haiku")) return "haiku";
+      if (id.includes("sonnet")) return "sonnet";
+      if (id.includes("opus")) return "opus";
+      return custom.model;
+    }
+    return "inherit";
+  }
 
-      const displayName = getDisplayName(typeName);
-      ctx.ui.notify(`Spawning ${displayName} agent...`, "info");
+  async function showAgentsMenu(ctx: ExtensionCommandContext) {
+    reloadCustomAgents();
+    const customNames = getCustomAgentNames();
 
-      const customConfig = getCustomAgentConfig(typeName);
-      const { systemPromptOverride, systemPromptAppend } = resolveCustomPrompt(customConfig);
+    // Build select options
+    const options: string[] = [];
 
-      const record = await manager.spawnAndWait(pi, ctx, typeName, prompt, {
-        description: prompt.slice(0, 40),
-        thinkingLevel: customConfig?.thinking,
-        systemPromptOverride,
-        systemPromptAppend,
-      });
+    // Running agents entry (only if there are active agents)
+    const agents = manager.listAgents();
+    if (agents.length > 0) {
+      const running = agents.filter(a => a.status === "running" || a.status === "queued").length;
+      const done = agents.filter(a => a.status === "completed" || a.status === "steered").length;
+      options.push(`Running agents (${agents.length}) — ${running} running, ${done} done`);
+    }
 
-      if (record.status === "error") {
-        ctx.ui.notify(`Agent failed: ${record.error}`, "warning");
-        return;
-      }
+    // Custom agents submenu (only if there are custom agents)
+    if (customNames.length > 0) {
+      options.push(`Custom agents (${customNames.length})`);
+    }
 
-      const duration = formatDuration(record.startedAt, record.completedAt);
-      const statusNote = getStatusNote(record.status);
-
-      // Send the result as a message so it appears in the conversation
-      pi.sendMessage(
-        {
-          customType: "agent-result",
-          content: [
-            {
-              type: "text",
-              text:
-                `**${displayName}** agent completed in ${duration} (${record.toolUses} tool uses)${statusNote}\n\n` +
-                (record.result ?? "No output."),
-            },
-          ],
-          display: true,
-        },
-        { triggerTurn: false },
-      );
-    },
-  });
+    // Actions
+    options.push("Create new agent");
+    options.push("Settings");
 
-  // ---- /agents command ----
+    // Show built-in types below the select as informational text (like Claude does)
+    const maxBuiltin = Math.max(...SUBAGENT_TYPES.map(t => t.length));
+    const builtinLines = SUBAGENT_TYPES.map(t => {
+      const model = BUILTIN_MODEL_LABELS[t] ?? "inherit";
+      return `  ${t.padEnd(maxBuiltin)} · ${model}`;
+    });
 
-  pi.registerCommand("agents", {
-    description: "List all agents with status",
-    handler: async (_args, ctx) => {
-      const agents = manager.listAgents();
+    const noAgentsMsg = customNames.length === 0 && agents.length === 0
+      ? "No agents found. Create specialized subagents that can be delegated to.\n\n" +
+        "Each subagent has its own context window, custom system prompt, and specific tools.\n\n" +
+        "Try creating: Code Reviewer, Security Auditor, Test Writer, or Documentation Writer.\n\n"
+      : "";
+
+    ctx.ui.notify(
+      `${noAgentsMsg}Built-in (always available):\n${builtinLines.join("\n")}`,
+      "info",
+    );
+
+    const choice = await ctx.ui.select("Agents", options);
+    if (!choice) return;
+
+    if (choice.startsWith("Running agents (")) {
+      await showRunningAgents(ctx);
+      await showAgentsMenu(ctx);
+    } else if (choice.startsWith("Custom agents (")) {
+      await showCustomAgentsList(ctx);
+      await showAgentsMenu(ctx);
+    } else if (choice === "Create new agent") {
+      await showCreateWizard(ctx);
+    } else if (choice === "Settings") {
+      await showSettings(ctx);
+      await showAgentsMenu(ctx);
+    }
+  }
+
+  async function showCustomAgentsList(ctx: ExtensionCommandContext) {
+    const customNames = getCustomAgentNames();
+    if (customNames.length === 0) {
+      ctx.ui.notify("No custom agents.", "info");
+      return;
+    }
+
+    // Compute max width of "name · model" for alignment
+    const entries = customNames.map(name => {
+      const cfg = getCustomAgentConfig(name);
+      const model = getModelLabel(name);
+      const prefix = `${name} · ${model}`;
+      return { prefix, desc: cfg?.description ?? name };
+    });
+    const maxPrefix = Math.max(...entries.map(e => e.prefix.length));
 
-      if (agents.length === 0) {
-        ctx.ui.notify("No agents have been spawned yet.", "info");
-        return;
+    const options = entries.map(({ prefix, desc }) =>
+      `${prefix.padEnd(maxPrefix)} — ${desc}`,
+    );
+
+    const choice = await ctx.ui.select("Custom agents", options);
+    if (!choice) return;
+
+    const agentName = choice.split(" · ")[0];
+    if (getCustomAgentConfig(agentName)) {
+      await showAgentDetail(ctx, agentName);
+    }
+  }
+
+  async function showRunningAgents(ctx: ExtensionCommandContext) {
+    const agents = manager.listAgents();
+    if (agents.length === 0) {
+      ctx.ui.notify("No agents.", "info");
+      return;
+    }
+
+    // Show as a selectable list for potential future actions
+    const options = agents.map(a => {
+      const dn = getDisplayName(a.type);
+      const dur = formatDuration(a.startedAt, a.completedAt);
+      return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
+    });
+
+    await ctx.ui.select("Running agents", options);
+  }
+
+  async function showAgentDetail(ctx: ExtensionCommandContext, name: string) {
+    const file = findAgentFile(name);
+    if (!file) {
+      ctx.ui.notify(`Agent file not found for "${name}".`, "warning");
+      return;
+    }
+
+    const choice = await ctx.ui.select(name, ["Edit", "Delete", "Back"]);
+    if (!choice || choice === "Back") return;
+
+    if (choice === "Edit") {
+      const content = readFileSync(file.path, "utf-8");
+      const edited = await ctx.ui.editor(`Edit ${name}`, content);
+      if (edited !== undefined && edited !== content) {
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(file.path, edited, "utf-8");
+        reloadCustomAgents();
+        ctx.ui.notify(`Updated ${file.path}`, "info");
       }
+    } else if (choice === "Delete") {
+      const confirmed = await ctx.ui.confirm("Delete agent", `Delete ${name} from ${file.location} (${file.path})?`);
+      if (confirmed) {
+        unlinkSync(file.path);
+        reloadCustomAgents();
+        ctx.ui.notify(`Deleted ${file.path}`, "info");
+      }
+    }
+  }
 
-      const lines: string[] = [];
-      const counts: Record<string, number> = {};
-      for (const a of agents) counts[a.status] = (counts[a.status] ?? 0) + 1;
+  async function showCreateWizard(ctx: ExtensionCommandContext) {
+    const location = await ctx.ui.select("Choose location", [
+      "Project (.pi/agents/)",
+      "Personal (~/.pi/agent/agents/)",
+    ]);
+    if (!location) return;
+
+    const targetDir = location.startsWith("Project") ? projectAgentsDir() : personalAgentsDir();
+
+    const method = await ctx.ui.select("Creation method", [
+      "Generate with Claude (recommended)",
+      "Manual configuration",
+    ]);
+    if (!method) return;
+
+    if (method.startsWith("Generate")) {
+      await showGenerateWizard(ctx, targetDir);
+    } else {
+      await showManualWizard(ctx, targetDir);
+    }
+  }
 
-      lines.push(
-        `${agents.length} agent(s): ${counts.running ?? 0} running, ${(counts.completed ?? 0) + (counts.steered ?? 0)} completed, ${counts.stopped ?? 0} stopped, ${counts.aborted ?? 0} aborted, ${counts.error ?? 0} errored`,
-      );
-      lines.push("");
+  async function showGenerateWizard(ctx: ExtensionCommandContext, targetDir: string) {
+    const description = await ctx.ui.input("Describe what this agent should do");
+    if (!description) return;
 
-      for (let i = 0; i < agents.length; i++) {
-        const a = agents[i];
-        const connector = i === agents.length - 1 ? "└─" : "├─";
-        const displayName = getDisplayName(a.type);
-        const duration = formatDuration(a.startedAt, a.completedAt);
+    const name = await ctx.ui.input("Agent name (filename, no spaces)");
+    if (!name) return;
 
-        lines.push(
-          `${connector} ${displayName} (${a.description}) · ${a.toolUses} tool uses · ${a.status} · ${duration}`,
-        );
+    // Validate name
+    if (isValidType(name) && !getCustomAgentConfig(name)) {
+      ctx.ui.notify(`"${name}" conflicts with a built-in agent type.`, "warning");
+      return;
+    }
+
+    if (!mkdirSync(targetDir, { recursive: true }) && !existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+
+    const targetPath = join(targetDir, `${name}.md`);
+    if (existsSync(targetPath)) {
+      const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+      if (!overwrite) return;
+    }
+
+    ctx.ui.notify("Generating agent definition...", "info");
+
+    const generatePrompt = `Create a custom pi sub-agent definition file based on this description: "${description}"
+
+Write a markdown file to: ${targetPath}
+
+The file format is a markdown file with YAML frontmatter and a system prompt body:
+
+\`\`\`markdown
+---
+description: <one-line description shown in UI>
+tools: <comma-separated built-in tools: read, bash, edit, write, grep, find, ls. Use "none" for no tools. Omit for all tools>
+model: <optional model as "provider/modelId", e.g. "anthropic/claude-haiku-4-5-20251001". Omit to inherit parent model>
+thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit>
+max_turns: <optional max agentic turns, default 50. Omit for default>
+prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
+extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
+skills: <true (inherit all), false (none). Default: true>
+inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
+run_in_background: <true to run in background by default. Default: false>
+isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
+---
+
+<system prompt body — instructions for the agent>
+\`\`\`
+
+Guidelines for choosing settings:
+- For read-only tasks (review, analysis): tools: read, bash, grep, find, ls
+- For code modification tasks: include edit, write
+- Use prompt_mode: append if the agent should keep the default system prompt and add specialization on top
+- Use prompt_mode: replace for fully custom agents with their own personality/instructions
+- Set inherit_context: true if the agent needs to know what was discussed in the parent conversation
+- Set isolated: true if the agent should NOT have access to MCP servers or other extensions
+- Only include frontmatter fields that differ from defaults — omit fields where the default is fine
+
+Write the file using the write tool. Only write the file, nothing else.`;
+
+    const record = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
+      description: `Generate ${name} agent`,
+      maxTurns: 5,
+    });
+
+    if (record.status === "error") {
+      ctx.ui.notify(`Generation failed: ${record.error}`, "warning");
+      return;
+    }
+
+    reloadCustomAgents();
+
+    if (existsSync(targetPath)) {
+      ctx.ui.notify(`Created ${targetPath}`, "info");
+    } else {
+      ctx.ui.notify("Agent generation completed but file was not created. Check the agent output.", "warning");
+    }
+  }
+
+  async function showManualWizard(ctx: ExtensionCommandContext, targetDir: string) {
+    // 1. Name
+    const name = await ctx.ui.input("Agent name (filename, no spaces)");
+    if (!name) return;
+
+    if (isValidType(name) && !getCustomAgentConfig(name)) {
+      ctx.ui.notify(`"${name}" conflicts with a built-in agent type.`, "warning");
+      return;
+    }
+
+    // 2. Description
+    const description = await ctx.ui.input("Description (one line)");
+    if (!description) return;
+
+    // 3. Tools
+    const toolChoice = await ctx.ui.select("Tools", ["all", "none", "read-only (read, bash, grep, find, ls)", "custom..."]);
+    if (!toolChoice) return;
+
+    let tools: string;
+    if (toolChoice === "all") {
+      tools = BUILTIN_TOOL_NAMES.join(", ");
+    } else if (toolChoice === "none") {
+      tools = "none";
+    } else if (toolChoice.startsWith("read-only")) {
+      tools = "read, bash, grep, find, ls";
+    } else {
+      const customTools = await ctx.ui.input("Tools (comma-separated)", BUILTIN_TOOL_NAMES.join(", "));
+      if (!customTools) return;
+      tools = customTools;
+    }
+
+    // 4. Model
+    const modelChoice = await ctx.ui.select("Model", [
+      "inherit (parent model)",
+      "haiku",
+      "sonnet",
+      "opus",
+      "custom...",
+    ]);
+    if (!modelChoice) return;
+
+    let modelLine = "";
+    if (modelChoice === "haiku") modelLine = "\nmodel: anthropic/claude-haiku-4-5-20251001";
+    else if (modelChoice === "sonnet") modelLine = "\nmodel: anthropic/claude-sonnet-4-6";
+    else if (modelChoice === "opus") modelLine = "\nmodel: anthropic/claude-opus-4-6";
+    else if (modelChoice === "custom...") {
+      const customModel = await ctx.ui.input("Model (provider/modelId)");
+      if (customModel) modelLine = `\nmodel: ${customModel}`;
+    }
+
+    // 5. Thinking
+    const thinkingChoice = await ctx.ui.select("Thinking level", [
+      "inherit",
+      "off",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+    ]);
+    if (!thinkingChoice) return;
+
+    let thinkingLine = "";
+    if (thinkingChoice !== "inherit") thinkingLine = `\nthinking: ${thinkingChoice}`;
+
+    // 6. System prompt
+    const systemPrompt = await ctx.ui.editor("System prompt", "");
+    if (systemPrompt === undefined) return;
+
+    // Build the file
+    const content = `---
+description: ${description}
+tools: ${tools}${modelLine}${thinkingLine}
+prompt_mode: replace
+---
+
+${systemPrompt}
+`;
+
+    mkdirSync(targetDir, { recursive: true });
+    const targetPath = join(targetDir, `${name}.md`);
+
+    if (existsSync(targetPath)) {
+      const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+      if (!overwrite) return;
+    }
+
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(targetPath, content, "utf-8");
+    reloadCustomAgents();
+    ctx.ui.notify(`Created ${targetPath}`, "info");
+  }
 
-        if (a.status === "error" && a.error) {
-          const indent = i === agents.length - 1 ? "   " : "│  ";
-          lines.push(`${indent} ⎿  Error: ${a.error.slice(0, 100)}`);
+  async function showSettings(ctx: ExtensionCommandContext) {
+    const choice = await ctx.ui.select("Settings", [
+      `Max concurrency (current: ${manager.getMaxConcurrent()})`,
+      `Default max turns (current: ${getDefaultMaxTurns()})`,
+      `Grace turns (current: ${getGraceTurns()})`,
+    ]);
+    if (!choice) return;
+
+    if (choice.startsWith("Max concurrency")) {
+      const val = await ctx.ui.input("Max concurrent background agents", String(manager.getMaxConcurrent()));
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          manager.setMaxConcurrent(n);
+          ctx.ui.notify(`Max concurrency set to ${n}`, "info");
+        } else {
+          ctx.ui.notify("Must be a positive integer.", "warning");
         }
-        if (a.session) {
-          const indent = i === agents.length - 1 ? "   " : "│  ";
-          lines.push(`${indent} ⎿  ID: ${a.id} (resumable)`);
+      }
+    } else if (choice.startsWith("Default max turns")) {
+      const val = await ctx.ui.input("Default max turns before wrap-up", String(getDefaultMaxTurns()));
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          setDefaultMaxTurns(n);
+          ctx.ui.notify(`Default max turns set to ${n}`, "info");
+        } else {
+          ctx.ui.notify("Must be a positive integer.", "warning");
         }
       }
+    } else if (choice.startsWith("Grace turns")) {
+      const val = await ctx.ui.input("Grace turns after wrap-up steer", String(getGraceTurns()));
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          setGraceTurns(n);
+          ctx.ui.notify(`Grace turns set to ${n}`, "info");
+        } else {
+          ctx.ui.notify("Must be a positive integer.", "warning");
+        }
+      }
+    }
+  }
 
-      ctx.ui.notify(lines.join("\n"), "info");
-    },
+  pi.registerCommand("agents", {
+    description: "Manage agents",
+    handler: async (_args, ctx) => { await showAgentsMenu(ctx); },
   });
 }