pi Desktop GUI for Independent Developers: Running the pi SDK within Electron, reusing ~/.pi/agent authentication, configurations, and JSONL sessions, and replacing the terminal-based TUI interaction with a timeline view, tool cards, diff review, and an extension compatibility layer.
Core Concepts
1. Sessions Based on pi
- Dialogue content, tool call logs, branching, and compression info strictly follow the JSONL session files written by pi in ~/.pi/agent/sessions/.
- The desktop app does not create a separate "chat history database" to replace pi; it only stores local application preferences like window layouts, recent projects, extension toggles, and adapter overrides.
- Benefit: You can seamlessly switch between the terminal pi and desktop pi on the same session; uninstalling the desktop app won't lose your conversation history.
2. Shared Configuration and Authentication
- Model accounts, settings.json, extension package lists, and project-specific .pi/ resources follow the exact same paths and rules as the terminal version.
- Changes made in Desktop Settings → Pi are written back to the global settings.json; Skill toggles and other settings are applied to the global configuration rather than being "mock-enabled" only within the desktop app.
3. Extensions: Compatibility Layer + Adapters instead of Modifying Plugin Source
- Extensions typically use TUI in the terminal (selections, confirmations, questionnaires, tool result cards, /commands for config). The desktop app lacks a terminal canvas.
- Compatibility Layer: Universally intercepts UI requests from extensions and transforms them into Electron dialogs, timeline cards, or settings forms.
- Adapters: Each extension has a specification for "how to display/configure on desktop and which commands need special handling" (built into the app, with JSON overrides available for advanced users).
- Principle: Do not touch the extension npm packages or fork pi; manage differences through adapter specifications and documentation.
- AI-Assisted Adapter Writing: See the repository's doc/ folder (the adapter-authoring-guide.md can be fed to a model to generate custom adapter.json files).
