<2-3 sentences summarising what the project addresses and solves, the target audience, and the benefit.> This project addresses the challenge of enabling AI agents, specifically the Pi coding agent, to autonomously control interactive command-line interfaces (CLIs). It provides an observable TUI overlay with full PTY emulation, allowing agents to manage sessions like editors, REPLs, or long-running processes while users can monitor in real-time and take over control instantly. This enhances agent capabilities for complex CLI-driven tasks.

How It Works

The core mechanism leverages node-pty to create a pseudo-terminal (PTY) environment, making subprocesses believe they are interacting with a real terminal. xterm-headless handles terminal emulation, rendering the output within a TUI overlay managed by the Pi agent. This approach ensures token efficiency and provides a seamless user experience, combining agent automation with direct user oversight and intervention capabilities.

Quick Start & Requirements

• Install: npm install pi-interactive-shell or via Pi: pi install npm:pi-interactive-shell.
• Prerequisites: Node.js and build tools for node-pty (e.g., Xcode CLI tools on macOS).
• Links: No direct quick-start or demo links provided in the README.

Highlighted Details

• Three Operational Modes:
  • Interactive: Agent execution blocks until the session ends; ideal for editors or REPLs where immediate results or user control are paramount.
  • Hands-Free: Agent returns immediately, polling for output; suitable for monitoring long-running processes like dev servers.
  • Dispatch: Agent returns immediately, receiving a notification upon session completion; optimized for delegating tasks to sub-agents.
• Universal CLI Compatibility: Supports any interactive CLI, including editors (vim), database shells (psql), remote access (ssh), build processes (npm run dev), and complex interactive commands (git rebase -i).
• Seamless User Intervention: Users can type to instantly take over control, use keyboard shortcuts (Ctrl+T to transfer output, Ctrl+B to background, Ctrl+Q for menus) to manage sessions.
• Headless Execution: The background: true option allows for invisible, headless operation, enabling multiple concurrent background dispatches.
• Example Workflow: Includes prompt templates demonstrating a full development pipeline with Codex CLI, involving plan review, implementation, and code review stages.

Maintenance & Community

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

Licensing & Compatibility

No license information is explicitly stated in the provided README text.

Limitations & Caveats

• Platform Support: Primarily tested on macOS; Linux support is experimental.
• TUI Rendering: Some Text-based User Interface (TUI) applications may exhibit rendering quirks.
• Rate Limiting: A configurable 60-second rate limit exists between agent queries to prevent excessive polling.