@adamjen/pi-one-subagent-at-a-time

Enforces sequential subagent execution — prevents concurrent subagent spawns.

---

Why This Exists

This extension was born from a real hardware constraint.

I'm running a Qwen3.6-27B orchestrator on an RTX 3090 (24GB VRAM) using llama-swap for model swapping between agents. The orchestrator would naturally want to spawn multiple subagents simultaneously — but each subagent spawn triggers a model swap, which means:

1. Unload current model from VRAM
2. Load new model into VRAM (takes seconds per swap)
3. Reload full context (adds more overhead)

With 3-4 agents spawning concurrently, this meant constant swapping — models loading and unloading in rapid succession. The time overhead was massive: what should take 10 seconds of actual work would take 60+ seconds just waiting for model swaps to complete.

The solution? Force subagents to run one at a time. No concurrent spawns, no model swapping chaos, no unnecessary context reloads. Just clean sequential execution.

If you're running local models on a single-GPU setup and experiencing similar slowdowns from agent spawning, this extension solves that problem.

---

What It Does

Blocks concurrent subagent() tool calls. When one subagent is already running, subsequent spawn attempts are blocked with a clear message until the first completes.

Before: Orchestrator spawns 3 agents simultaneously → model swapping chaos → 60+ second delays
After: Agents run sequentially → no swapping overhead → clean execution flow

---

Install

pi install npm:@adamjen/pi-one-subagent-at-a-time

Or try without installing:

pi -e npm:@adamjen/pi-one-subagent-at-a-time

For local development:

pi install ~/projects/pi-one-subagent-at-a-time

---

How It Works

The extension hooks into three pi lifecycle events:

1. session_start — Shows status indicator ("🔒 agent-gate active")
2. tool_call — Intercepts subagent calls; blocks if one is already pending
3. agent_end — Decrements the pending counter when an agent finishes

// Simplified logic
let pending = 0;

pi.on("tool_call", async (event, ctx) => {
  if (event.toolName === "subagent") {
    if (pending >= 1) {
      return { block: true, reason: "BLOCKED: subagent already running. Wait for steer-back." };
    }
    pending++;
  }
});

pi.on("agent_end", async () => {
  if (pending > 0) pending--;
});

---

Target Audience

This extension is ideal for users who:

• Run local models on single-GPU hardware (RTX 3090, 4090, etc.)
• Use model swapping (llama-swap or similar) between agents
• Experience slowdowns from concurrent agent spawns causing context reloads
• Want predictable sequential execution rather than parallel chaos

If you have multiple GPUs or cloud models with no swap overhead, this extension is optional — but it still enforces cleaner execution patterns.

---

Configuration

No configuration needed — works out of the box with a hard limit of 1 concurrent subagent.

The status indicator shows in the pi TUI:

• 🔒 agent-gate active — extension loaded, no agents running
• 🔒 1 running — one subagent is currently executing

---

Browse All Packages

pi.dev/packages/@adamjen/pi-one-subagent-at-a-time?name=adamjen — browse all my pi extensions.

License

MIT