This project introduces interactive sub-agents for the pi coding agent, enabling asynchronous execution and management of agent sessions within terminal multiplexer panes. It allows the main agent to continue working while sub-agents operate in the background, with results seamlessly integrated back into the primary session. This enhances productivity for developers and power users by facilitating parallel task execution and maintaining a responsive interface.

How It Works

The core mechanism involves calling subagent(), which returns immediately while the sub-agent runs in a dedicated multiplexer pane. A live widget displays active agents, their progress, and elapsed time. Upon completion, sub-agent results are asynchronously steered back into the main pi session as notifications, triggering new turns for processing. This design supports concurrent execution of multiple sub-agents, each returning its result independently.

Quick Start & Requirements

• Install: pi install git:github.com/HazAT/pi-interactive-subagents
• Prerequisites: A supported multiplexer (cmux, tmux, zellij, WezTerm) and the pi agent.
• Run: Start pi within a multiplexer (e.g., cmux pi, tmux new -A -s pi 'pi', zellij --session pi, or pi in WezTerm).
• Optional: Set PI_SUBAGENT_MUX environment variable to force a specific multiplexer backend.

Highlighted Details

• Asynchronous Sub-agents: Spawn, orchestrate, and manage background agent sessions non-blockingly, with a live progress widget.
• Multiplexer Integration: Supports cmux, tmux, zellij, and WezTerm, updating tab/window titles to show workflow phases.
• Bundled Agents: Includes planner, scout, worker, reviewer, and visual-tester for comprehensive coding workflows.
• Workflows: Features /plan for end-to-end planning-to-implementation pipelines and /iterate for context-rich, focused fixes.
• Custom Agents: Enables defining custom agents via .md files in project-local (.pi/agents/) or global (~/.pi/agent/agents/) directories.
• Session Artifacts: Tools (write_artifact, read_artifact) for managing session-scoped file storage.
• Tool Access Control: Granular control over agent capabilities via frontmatter (spawning: false, deny-tools).

Maintenance & Community

No specific details regarding contributors, sponsorships, or community channels (e.g., Discord, Slack) are provided in the README.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license is permissive, allowing for commercial use and integration with closed-source projects.

Limitations & Caveats

The README does not explicitly detail known bugs, alpha status, or deprecation warnings. The functionality is dependent on the pi agent and a compatible terminal multiplexer environment. Custom agent definitions require adherence to a specific frontmatter structure.