https://github.com/psylsph/pi-desktop
A native desktop app for the pi coding agent — your AI pair programmer in a beautiful Electron UI
https://github.com/psylsph/pi-desktop
ai chatbot coding-agent desktop-app developer-tools electron productivity typescript
Last synced: 27 days ago
JSON representation
A native desktop app for the pi coding agent — your AI pair programmer in a beautiful Electron UI
- Host: GitHub
- URL: https://github.com/psylsph/pi-desktop
- Owner: psylsph
- License: mit
- Created: 2026-05-08T12:22:02.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-08T14:29:21.000Z (about 2 months ago)
- Last Synced: 2026-05-08T14:32:04.059Z (about 2 months ago)
- Topics: ai, chatbot, coding-agent, desktop-app, developer-tools, electron, productivity, typescript
- Language: TypeScript
- Homepage: https://github.com/psylsph/pi-desktop
- Size: 149 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-pi-coding-agent - psylsph-pi-desktop
README
# Pi Desktop
[](https://github.com/psylsph/pi-desktop/actions)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://www.electronjs.org/)
[](https://www.typescriptlang.org/)
> A cross-platform desktop application for the [pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) — your AI-powered coding companion.
[](https://github.com/psylsph/pi-desktop)
## ✨ Features
- 🤖 **Chat interface** — Send prompts and receive streaming responses with markdown rendering
- 📝 **Rich markdown** — Headers, links, lists, blockquotes, code blocks with line numbers & copy button
- 🧠 **Thinking blocks** — Collapsible display of agent reasoning (when using reasoning models)
- 🔧 **Tool call visualization** — Real-time streaming of tool executions with status indicators (running, success, error)
- 🎯 **Model selector** — Browse and switch between available models grouped by provider
- ⚙️ **Thinking level controls** — Adjust agent thinking depth (off, low, medium, high)
- 💾 **Session management** — Create new sessions, compact context, restore previous sessions
- 📜 **Session history** — Browse and restore previous sessions from the sidebar
- 📤 **Conversation export** — Export chats as Markdown or JSON
- 📁 **Project selector** — Choose a working directory via native OS dialog
- 🌙☀️ **Dark & light themes** — Tokyo Night dark theme + light theme, toggle and persisted
- 🖱️ **Drag & drop files** — Drop files onto the chat to include paths in prompts
- 🔔 **Sound notifications** — Audio feedback when agent completes tasks or errors
- 🪟 **Window persistence** — Remembers window size, position, and state across launches
- 🔄 **Auto-update checks** — Checks for new versions on launch with notification banner
- ⌨️ **Keyboard shortcuts** — Enter to send, Shift+Enter for newlines, Escape to abort
- 🔔 **Toast notifications** — Non-intrusive feedback for state changes and errors
## 🚀 Quick Start
**Prerequisites:** Node.js 18+ and an API key for at least one supported provider (e.g., `ANTHROPIC_API_KEY`)
```bash
# Clone and install
git clone https://github.com/psylsph/pi-desktop.git
cd pi-desktop
npm install
# Run in development
npm run dev
# Build for distribution
npm run dist
```
### Platform-Specific Builds
| Command | Output |
|----------------------|-------------------------------|
| `npm run dist:mac` | `.dmg`, `.zip` |
| `npm run dist:linux` | `.AppImage`, `.deb` |
| `npm run dist:win` | NSIS installer, portable `.exe` |
## 📖 Usage
Pi Desktop reads your existing pi agent configuration from `~/.pi/agent/`:
| File | Purpose |
|-------------------|----------------------------------|
| `auth.json` | API keys and OAuth tokens |
| `settings.json` | Global agent settings |
| `models.json` | Custom model definitions |
| `extensions/` | Extensions |
| `skills/` | Skills |
The app automatically uses these on launch. Configure your API keys first via the pi CLI:
```bash
# Set your API key
pi config set ANTHROPIC_API_KEY your_key_here
# Then launch Pi Desktop
npm run dev
```
## 🆚 Comparison
| Feature | Pi Desktop | VS Code Extension | Terminal CLI |
|---------|-----------|-------------------|--------------|
| **Interface** | Native desktop app with dedicated UI | Integrated into VS Code sidebar | Terminal-based (TUI) |
| **Performance** | Lightweight, standalone process | Shares VS Code resources | Minimal overhead |
| **Streaming** | Real-time with markdown rendering | Real-time but editor-bound | Real-time with ansi formatting |
| **Tool Visualization** | Dedicated panel with status indicators | Inline in chat output | Inline in terminal |
| **Session Management** | GUI buttons and menu items | VS Code command palette | CLI commands |
| **Multi-window** | Multiple instances possible | Single instance | Multiple terminals |
| **Thinking Blocks** | Collapsible panels | Inline display | Inline display |
| **Distraction-free** | Focused coding environment | Editor integration | Minimalist |
| **Setup** | npm install + run | VS Code extension install | npm install -g |
| **Best for** | Dedicated coding sessions | Editor workflow | Terminal power users |
**Why Pi Desktop?**
- **Focused workflow**: Dedicated app means no context switching from your editor
- **Better UX**: Native menus, keyboard shortcuts, and modal dialogs
- **Always ready**: No need to open VS Code just to chat with your agent
- **Visual feedback**: Rich tool call visualization and status updates
- **Cross-platform**: Works on Windows, macOS, and Linux with native builds
## 🏗️ Architecture
```
pi-desktop/
├── src/
│ ├── main/
│ │ ├── main.ts # Electron main process — agent lifecycle, IPC handlers
│ │ └── preload.cjs # Context bridge (CommonJS) — safe IPC to renderer
│ ├── renderer/
│ │ ├── index.html # UI layout — sidebar, message area, input
│ │ ├── renderer.js # Renderer logic — event handling, message rendering
│ │ └── styles.css # Tokyo Night dark theme
│ └── shared/
│ └── types.ts # Shared TypeScript types and IPC channel constants
├── tests/
│ ├── e2e.test.ts
│ ├── renderer.test.ts
│ ├── sdk.test.ts
│ └── types.test.ts
├── package.json
├── tsconfig.json
└── vitest.config.ts
```
### How It Works
1. The **main process** (`main.ts`) initializes an agent session using the `@earendil-works/pi-coding-agent` SDK on startup
2. A **preload script** (`preload.cjs`) exposes a `window.piDesktop` API to the renderer via Electron's `contextBridge`
3. The **renderer** (`renderer.js`) communicates with the main process exclusively through IPC — sending prompts, switching models, and subscribing to streaming events (text deltas, thinking blocks, tool calls)
4. Session events are forwarded from the SDK subscription to the renderer, which renders messages, tool blocks, and status updates in real time
### IPC Channels
All communication between renderer and main process uses typed IPC channels defined in `src/shared/types.ts`:
- **Renderer → Main**: `sendPrompt`, `abort`, `newSession`, `getState`, `getMessages`, `getModels`, `setModel`, `setThinking`, `compact`, `setWorkingDir`, `quit`
- **Main → Renderer**: `session:event`, `session:state`, `session:messages`, `session:models`, `session:status`
## 🧪 Testing
```bash
npm test # run once
npm run test:watch # watch mode
```
Tests use [Vitest](https://vitest.dev/) and live in `tests/`.
## 🛠️ Tech Stack
- [Electron](https://www.electronjs.org/) 36 — desktop shell
- [TypeScript](https://www.typescriptlang.org/) 5 — main process and shared types
- [Vitest](https://vitest.dev/) 4 — testing
- [electron-builder](https://www.electron.build/) — packaging and distribution
- `@earendil-works/pi-coding-agent` — pi SDK
## 📄 License
[MIT](LICENSE) © [Stuart Harding](https://github.com/psylsph)
## 🔗 Links
- [pi CLI Documentation](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
- [Report Issues](https://github.com/psylsph/pi-desktop/issues)
- [Contributions Welcome](https://github.com/psylsph/pi-desktop/pulls)