pi-loopflows

Build deterministic AI workflows out of Pi subagents.

Think of loopflows as LEGO for subagents. You take small specialist agents, connect them into a process, add gates where decisions matter, and let the workflow move forward, branch, loop back, or stop based on explicit results. Instead of one giant prompt, you get a reusable structure for how agents collaborate: steps, feedback loops, stop rules, and saved evidence.

Why loopflows

Linear chains are useful, but real work is not always linear. A reviewer can request changes. A validator can reject missing evidence. A planner can reveal that the task is blocked. A builder may need several focused passes before the result is safe to accept.

Loopflows make that control flow explicit:

step → step → gate
             ↓
          approved → continue
          changes_requested → loop back
          blocked → stop

The philosophy is simple: AI should work through a process, not just produce a confident answer. A loopflow defines who does the work, who checks it, what counts as success, how many attempts are allowed, where evidence is saved, and when the run must stop instead of guessing.

Install

pi install npm:pi-loopflows

pi-loopflows uses Pi subagent definitions as its first backend. Install pi-subagents if you have not already:

pi install npm:pi-subagents

Then reload Pi:

/reload

What you get

Tool

loopflow_run({
  workflow: "launch-control",
  task: "Implement this approved backend plan",
  maxIterations: 3
})

Commands

/loopflow-list
/loopflow launch-control -- Implement this approved backend plan

Built-in loopflows

• launch-control — plan-as-contract implementation loop with builder/reviewer feedback and final audit.
• build-review — small generic build → review → fix loop for scoped implementation tasks.
• plan-review — planning loop that lets a reviewer reject vague or unsafe plans before implementation.

Advanced Features (v0.2.0)

Real-time TUI Monitoring & Streaming Panel

v0.2.0 introduces a rich full-screen TUI monitor dashboard to make loopflow execution fully transparent.

• Open the Panel: Use /loopflow-monitor command or press ctrl+shift+l to toggle the full-screen visualization overlay.
• Tab Navigation: Toggle between [1] GENERAL MAP (workflow graph and sequence history) and [2] AGENT THOUGHTS (real-time stream of what agents are thinking, executing, or what tools are being invoked) using the Left/Right arrow keys or number keys 1 and 2.
• Deep Inspect: Native arrow key navigation inside the dashboard lets you select and scroll through specific agent logs and full outputs without truncation.

Interactive Control Plane & Agent Steering

You are no longer a passive observer of the loop. The TUI panel adds real-time interaction capabilities:

• Run Controls: Press p to pause, r to resume, or x to terminate active loopflow execution at any safe step boundary.
• Live Steering Input Bar: Focus the input bar by pressing m or i to send messages directly to the active worker.
• Delivery Modes: Toggle message delivery modes with ] before sending:
  • queue — messages are queued and injected as instructions into the agent's next step;
  • steer — injects instruction during active turn;
  • interrupt — instantly interrupts the current agent step, rewrites the task, and restarts the step with your new guidance.

Two-Layer Memory System (Mastra OM + Persistent Sessions)

To prevent agents from having amnesia between runs or bloating their context windows during long loops, v0.2.0 features a custom two-layer memory engine:

• Private Persistent Sessions: Subagents run with unique session IDs mapped to the workflow: loopflow-{workflowName}-{agentName}. This ensures each agent maintains an isolated, persistent memory "head" across workflow executions.
• Mastra-style Observational Memory: When loops run, the orchestrator triggers an automatic observeNow compaction on session shutdown. High-value discoveries, decisions, and outcomes are compressed into lightweight Markdown observations, which are automatically passed into the next iteration's prompt template via {loop.observations} and {loop.reflections} to drive coherent progress.

Loopflows as a constructor

Think of loopflows as LEGO for agent processes. A loopflow can use any available Pi subagent role:

• context-builder
• scout
• researcher
• planner
• worker
• reviewer
• oracle
• your own custom agents

You decide:

• which agent runs first;
• what each agent receives;
• which output is saved;
• which step is a gate;
• what statuses mean pass, retry, or stop;
• how many loop iterations are allowed;
• where artifacts go;
• what final audit should prove.

Today, the backend runs Pi-compatible subagents. The engine is intentionally built behind an adapter boundary, so future versions can add other compatible backends — Codex CLI, OpenCode, ACP workers, remote agents, or custom executors — without changing the loopflow concept.

Loopflow files

Loopflows are JSON files named:

*.loopflow.json

Discovery locations:

• bundled package loopflows;
• user loopflows: ~/.pi/agent/loopflows/;
• project loopflows: .pi/loopflows/.

Project loopflows are the easiest way to customize behavior for one repo.

Minimal example

{
  "name": "build-review",
  "description": "Build, review, and fix until approved.",
  "steps": [
    {
      "id": "plan",
      "agent": "planner",
      "task": "Plan this task: {task}"
    },
    {
      "loop": {
        "id": "build-review",
        "maxIterations": 3,
        "gateStep": "review",
        "passStatuses": ["approved"],
        "retryStatuses": ["changes_requested"],
        "stopStatuses": ["blocked"],
        "body": [
          {
            "id": "build",
            "agent": "worker",
            "task": "Build from plan: {outputs.plan}"
          },
          {
            "id": "review",
            "agent": "reviewer",
            "gate": { "type": "json-status" },
            "task": "Review and return JSON with status approved, changes_requested, or blocked."
          }
        ]
      }
    }
  ]
}

Template variables

• {task} — original user task.
• {previous} — previous step output.
• {outputs.stepId} — output from a named step.
• {outputs.stepId.output} — same as above, explicit form.
• {outputs.stepId.status} — parsed gate status.
• {outputs.stepId.json} — parsed gate JSON.
• {loop.iteration} — current loop iteration.
• {artifactsDir} — current run artifact directory.
• {params.name} — runtime params passed to loopflow_run.

Gate contract

Gate steps should return JSON. A typical reviewer gate returns:

{
  "status": "approved",
  "summary": "The implementation satisfies the plan.",
  "findings": [],
  "validation_gaps": [],
  "requires_user_decision": false
}

Common statuses:

• approved — move forward.
• changes_requested — loop back for another pass.
• blocked — stop; user or environment action is required.
• complete — final audit passed.
• incomplete — final audit failed.

Each loopflow decides which statuses pass, retry, or stop.

Artifacts

Every run writes evidence to:

<cwd>/.pi/loopflows/runs/<timestamp>-<workflow>/

Typical artifacts:

task.md
workflow.json
context.md
block-plan.md
build-1.md
review-1.json
final-audit.json
summary.md

This makes loopflows inspectable. You can see what each agent claimed, what the gate decided, and why the run stopped or passed.

Customization patterns

Make Launch Control stricter

Copy the bundled file:

mkdir -p .pi/loopflows
cp ~/.pi/agent/npm/node_modules/pi-loopflows/loopflows/launch-control.loopflow.json \
  .pi/loopflows/launch-control.loopflow.json

Then edit the project copy. Common changes:

• increase maxIterations;
• change reviewer to a custom security reviewer;
• add stricter validation language;
• add a docs or migration audit step;
• change stop statuses;
• make the final audit require complete only.

Create a lightweight workflow

Use build-review for small implementation tasks where full Launch Control is too formal.

/loopflow build-review -- Add validation to the import endpoint

Review a plan before coding

Use plan-review when you want a plan to be checked before a worker touches files.

/loopflow plan-review -- Plan the database migration for workspace roles

Backend design

The runtime uses an executor adapter boundary:

runAgent(agent, task, options) -> StepResult

Current backend:

• Pi subprocess agents compatible with pi-subagents agent definitions.

Future-compatible backend ideas:

• Codex CLI workers;
• OpenCode workers;
• ACP-compatible agents;
• remote worker pools;
• project-specific executors.

The point is that loopflows describe the process. The backend decides how each agent is actually executed.

When to use loopflows vs chains

Use normal Pi subagent chains when the process is linear:

scout → planner → worker

Use loopflows when a step can send work backward or stop the process:

worker → reviewer → worker → reviewer

If you need a feedback loop, a quality gate, a max iteration limit, or saved evidence, use a loopflow.

Versioning

pi-loopflows uses semantic versioning: MAJOR.MINOR.PATCH.

• PATCH for docs, bug fixes, prompt polish, validation improvements, and internal refactors with no user-facing behavior change.
• MINOR for new backward-compatible features, bundled loopflows, commands, options, fields, or adapter backends.
• MAJOR for breaking changes to loopflow JSON shape, template variables, gate semantics, commands, artifact paths, or adapter behavior.

See VERSIONING.md for the release checklist.

Status

pi-loopflows is early, but designed as a real product surface rather than a one-off script. The core model is intentionally small:

steps + loops + gates + artifacts + adapters

That is enough to build useful workflows without turning the extension into a giant orchestration platform.

License

MIT