Pi Dispatch

@codewithkenzo/pi-dispatch — Profile-based execution and queued task dispatch for the Pi coding agent.

Part of the Pi Rig suite.

Pi Dispatch registers execution primitives that let the agent launch tasks with named profiles, manage background jobs, inspect live work through the flow deck, and inject skills into subagent runs — without writing boilerplate for each new task type.

Quick demo

Shows the flow deck, profile routing, and a background run in one short capture.

Surfaces

| Type | Name | Purpose | |------|------|---------| | Tool | flow_run | Run a single task with a named profile (foreground or background) | | Tool | flow_batch | Run multiple tasks sequentially or in parallel | | Command | /flow or /flow manage | Open the interactive flow deck | | Command | /flow status | List active and completed jobs | | Command | /flow cancel <id> | Cancel a queued or running job | | Command | /flow profiles | List available profiles and their settings |

Profiles

Built-in profiles control reasoning level, iteration cap, and toolsets:

| Profile | Reasoning | Iterations | Toolsets | |---------|-----------|------------|----------| | explore | low | 11 | terminal, file | | research | medium | 18 | terminal, file, web | | coder | medium | 35 | code_execution | | debug | high | 20 | inherits | | browser | medium | 25 | browser | | ambivalent | medium | 18 | inherits |

Custom profiles are loaded from JSON:

• ~/.pi/agent/flow-profiles.json — global overrides
• <cwd>/.pi/flow-profiles.json — project-local (wins ties)

Architecture

index.ts              Extension entry — wires queue, tools, commands, session events
src/
  types.ts            TypeBox schemas + tagged errors
  queue.ts            In-memory job queue (Effect Ref)
  profiles.ts         Built-in profiles + file-based overrides
  executor.ts         Subprocess runner (Effect.callback + acquireUseRelease)
  vfs.ts              Skill file staging with temp file lifecycle
  tool.ts             flow_run tool
  batch-tool.ts       flow_batch tool
  commands.ts         /flow command handler
  deck/
    index.ts          showFlowDeck() — 3-zone TUI overlay factory
    state.ts          DeckState + feed dedup and sanitization
    header.ts         Zone 1 — title, badge, clock
    columns.ts        Zone 2 — profile panel and activity feed
    summary.ts        Zone 3 — scrollable subprocess output
    footer.ts         Zone 4 — keybind pills with key-flash feedback
    layout.ts         ANSI-preserving column fit utilities
    icons.ts          Nerd Font icons with ASCII fallback (PI_ASCII_ICONS=1)

Key patterns

• Effect at boundaries — async subprocess and tool execution stay in Effect-TS. Conversion to Promise happens only at the pi API surface via Effect.runPromise and Effect.runPromiseExit.
• Tagged errors — ProfileNotFoundError, SkillLoadError, SubprocessError, JobNotFoundError. No trailing () per Bun 1.3+ convention.
• acquireUseRelease — skill temp files are always cleaned up, even on subprocess failure or interruption.
• Session persistence — queue state is snapshotted on agent_end and restored on session_start.
• Deck TUI — AnimationTicker drives 4–8 fps render. withMotion() guards every animation primitive. fitAnsiColumn(text, width) handles ANSI-preserving column fit.

Install

pi install npm:@codewithkenzo/pi-dispatch

Or install all Pi Rig extensions at once:

bunx @codewithkenzo/pi-rig@latest

bun run setup
# or individually:
pi install ./extensions/flow-system

Prerequisites

• Bun >= 1.3
• Pi coding agent installed and on your PATH

Development

cd extensions/flow-system
bun install
bun run build       # runtime bundle for the Pi coding agent
bun run typecheck   # typecheck
bun test            # tests

Links

• Pi Rig suite — monorepo with all extensions, installer, and docs
• Pi coding agent — upstream runtime
• npm: @codewithkenzo/pi-dispatch
• Related: @codewithkenzo/pi-theme-switcher, @codewithkenzo/pi-gateway-messaging, @codewithkenzo/pi-notify-cron