pi-agent-workflows

A pi extension that lets an overseer model spawn typed workflow subagents from JSON.

What is implemented

• workflow_spawn tool: accepts a compact WorkflowPlan JSON string and runs subagents sequentially or in parallel.
• Floating workflow window: workflow_spawn opens a focused overlay with collapsible agent trees, tool-call overview, per-agent inspection, pricing, and controls.
• Status/statusbar accounting: subagent token/cost usage is reported without replacing other extension footers by default; legacy footer replacement is opt-in.
• Overlay controls: q closes, Esc aborts, Tab switches views, arrows/j/k select agents, and u/d or [/] scroll on keyboards without Page Up/Down.
• Individual inspection: workflow_inspect_agent, /workflow-inspect, or the overlay Inspect tab show one subagent’s task, model, output, messages, notes, events, usage, and controls.
• Prompt injection: workflow_prompt, /workflow-prompt, or p inside the overlay can steer active subagents while they run.
• Escape abort: pressing Esc in the overlay aborts the workflow and propagates cancellation to running subagents.
• Recursive spawning: agent classes can opt into canSpawn and restrict child classes.
• Per-agent model selection: use model on a class or spawn spec. Use @fast, @default, or @current sentinels.
• Inter-agent communication: subagents share workflow_send, workflow_receive, and workflow_blackboard.
• Global write locks: mutating bash commands must declare writePaths; locks prevent subagents from claiming the same file/path during a run.
• Bash for every subagent: the bash tool is mandatory for all spawned agents.
• Root skill inheritance: available/loaded skills from the overseer context are carried into subagent prompts.
• TypeScript API: register custom agent classes and custom workflow tools with createWorkflowExtension, defineAgentClass, and defineWorkflowTool.
• Main-agent skill: skills/pi-workflows/SKILL.md tells the agent to get an overview first, use workflows only for clearly defined substantial work, and route @fast/@default models appropriately.

Install

Install from npm:

pi install npm:pi-agent-workflows

Or install directly from GitHub:

pi install git:github.com/an2tha/pi-workflows

For local development, try a checkout without installing:

pi -e /path/to/pi-workflows/index.ts

Configure workflow model aliases, enable/disable the extension, and choose non-invasive status vs footer replacement mode:

/workflow-settings
/workflow-settings show
/workflow-settings disable
/workflow-settings enable
/workflow-settings footer status

Manually force workflows for a task when you know the extra cost is worthwhile:

/workflow-force <task>
/workflow-force-next <task>

Custom workflow ideas

Agents are encouraged to create task-specific workflow plans rather than reuse canned templates. Good custom shapes include:

• subsystem split: one agent per package/API/feature area
• risk split: compatibility, migration, concurrency, security, UX/accessibility
• ownership split: one writer per non-overlapping file group with write locks
• validation split: tests, typecheck/lint, repro scripts, docs examples, smoke checks
• release split: docs/examples, packaging, changelog/install verification

Use /workflow-classes to see registered classes, then assign custom ids, task text, dependencies, and limits for the current request.

Configure workflow behavior and fast/default model aliases in ~/.pi/agent/settings.json or .pi/settings.json:

{
  "workflows": {
    "enabled": true,
    "footerMode": "status",
    "fastModel": "openai-codex/codex-5.3-spark",
    "defaultModel": "anthropic/claude-sonnet-4-5"
  }
}

Environment variables are still supported as fallback:

PI_WORKFLOW_FAST_MODEL=openai-codex/codex-5.3-spark
PI_WORKFLOW_DEFAULT_MODEL=anthropic/claude-sonnet-4-5

Write locking

The subagent bash tool treats read commands as unlocked. Commands that look mutating are rejected unless they pass writePaths.

Example mutating bash call inside a custom workflow tool:

await ctx.bash("python3 scripts/update.py src/cache.ts", {
  writePaths: ["src/cache.ts"],
  lockTimeoutMs: 5000,
});

Locks are global to the engine and held for the workflow run. This prevents two subagents from owning the same file or a parent/child path concurrently.

TypeScript API sketch

import Type from "typebox";
import {
  createWorkflowExtension,
  defineAgentClass,
  defineWorkflowTool,
  textResult,
} from "pi-agent-workflows";

export default createWorkflowExtension({
  agentClasses: [
    defineAgentClass({
      name: "docs-writer",
      description: "Writes concise documentation from findings.",
      model: "@fast",
      tools: ["bash", "summarize_file"],
    }),
  ],
  tools: [
    defineWorkflowTool({
      name: "summarize_file",
      description: "Read a file and return a short summary.",
      parameters: Type.Object({ path: Type.String() }),
      async execute(params, ctx) {
        const quotedPath = JSON.stringify(params.path);
        const result = await ctx.bash(`python3 - <<'PY'\nfrom pathlib import Path\nprint(Path(${quotedPath}).read_text()[:2000])\nPY`);
        return textResult(result.stdout, result);
      },
    }),
  ],
});

Development

bun install
bun test
bunx tsc --noEmit