@adamjen/pi-one-subagent-at-a-time
Enforces sequential execution of sub-agents to eliminate model swapping overhead on single-GPU systems.
Install & Use
Copy this prompt and send it to your AI assistant (Claude / Cursor / TRAE / Codex / WorkBuddy etc.) to auto-install:
Help me install this AI Skill: @adamjen/pi-one-subagent-at-a-time. It is used for: Enforces sequential execution of sub-agents to eliminate model swapping overhead on single-GPU systems. Full Skill content: https://321skill.com/skills/adamjen-pi-one-subagent-at-a-time/raw/index.md Read that page and install it.
The prompt includes a link to the full Skill content. You can also view the full content.
This Skill addresses the issue of exploding model swapping overhead caused by concurrent sub-agents in a single-GPU environment. In practical development, when using tools like llama-swap to switch models between sub-agents, generating multiple sub-agents concurrently triggers frequent model loading and unloading—each switch taking several seconds, combined with context reloading, can extend a 10-second task to over 60 seconds.
Usage is straightforward: simply install the extension via pi install, and it takes effect without any configuration. Subsequently, all subagent() tool calls are automatically queued: while the first sub-agent runs, subsequent calls are blocked and return a clear prompt until the previous one completes. The pi TUI interface will display a "🔒 agent-gate active" status indicator.
It is ideal for developers or teams needing to run multiple Agents on a single GPU. This is particularly useful for users with limited VRAM hardware like RTX 3090/4090, who rely on model switching to schedule different sub-agents, and for workflows aiming to avoid parallel chaos and pursue predictable sequential execution.
It is recommended to use this Skill in conjunction with llama-swap or similar model swapping tools. Note that it only affects subagent() calls within the pi framework, does not impact other external parallel tasks, and is hard-limited to 1 concurrent agent without dynamic adjustment.
Key Features
Unlike common concurrency-limiting tools, it directly hooks into pi's `tool_call` and `agent_end` lifecycle events, precisely blocking at the point of sub-agent invocation rather than relying on external queues. This makes it highly targeted for single-GPU model swapping scenarios, whereas generic queue solutions cannot perceive model swap states.
Limitations
Applicable only within the pi framework; hard-limited to 1 concurrent sub-agent with no configurable concurrency adjustment. Does not support multi-GPU or cloud scenarios where model swapping overhead is absent.
FAQ
Is any additional configuration required after installation?
No, it works out-of-the-box, defaulting to a limit of 1 concurrent sub-agent. The pi TUI will display a status indicator.
Will it affect other parallel tools or scripts?
No, it only intercepts `subagent()` calls within the pi framework and does not impact external parallel tasks or system-level concurrency.
Installation guide for AI assistants
If your AI coding assistant (Claude Code, Cursor, TRAE etc.) can see this page, send it this message to auto-install:
Visit https://321skill.com/skills/adamjen-pi-one-subagent-at-a-time/raw/index.md to read the original Skill definition (Markdown format) for @adamjen/pi-one-subagent-at-a-time, and install it according to the instructions.
Raw Markdown URL for AI: /skills/adamjen-pi-one-subagent-at-a-time/raw/index.md