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, 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 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

From source

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