A desktop GUI application for the pi-coding-agent runtime, pi-gui provides a native user experience for interacting with AI coding agents. It targets users of the pi-coding-agent who seek enhanced session management, integrated tooling, and a structured interface, offering improved productivity and workflow organization.

How It Works

pi-gui is an Electron application that acts as a UI shell around the @earendil-works/pi-coding-agent runtime. It employs a standard Electron architecture with distinct main, preload, and renderer processes. The React-based renderer handles the user interface, communicating with the main process via a typed IPC surface. The main process manages windowing, session supervision, and integrates features like PTY terminals via node-pty. Crucially, pi-gui uses pi's JSONL session files as the authoritative source of truth for closed sessions, ensuring tight integration and avoiding divergent state. This approach allows for a rich desktop experience without forking the core agent runtime, maintaining close alignment with upstream pi developments.

Quick Start & Requirements

• Primary Install: Download the latest .dmg (macOS) or .AppImage (Linux) from the GitHub Releases page. On macOS, drag pi-gui.app to /Applications. Alternatively, use Homebrew on macOS: brew tap minghinmatthewlam/tap && brew install --cask pi-gui.
• Prerequisites: macOS (Apple Silicon) or Linux (AppImage). Requires valid model/provider authentication configured for pi (via OAuth or API key).
• Setup: Install pi-gui, configure model providers in Settings, add a workspace, and start a new thread.
• Links: Releases

Highlighted Details

• Threaded timeline view of agent sessions with collapsible tool calls.
• Git worktrees per thread for isolated parallel development.
• Multi-agent orchestration capabilities.
• Integrated PTY terminal for direct command-line interaction.
• Inline diff viewer for reviewing file changes.
• Composer enhancements: file @-mentions and drag-and-drop image attachments.
• Dedicated view for managing pi skills and extensions.
• Support for multiple model providers via OAuth or API key.

Maintenance & Community

The project is maintained by minghinmatthewlam. No specific community channels (like Discord/Slack) or detailed contributor information are provided in the README.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license permits commercial use and integration within closed-source projects.

Limitations & Caveats

The application is currently in public beta for macOS and Linux. Native computer use functionality is not built into pi-gui; it requires a separate computer-use-mcp server. Building from source is primarily intended for contributors.