Pi Agent Desktop
Turn the Pi Coding Agent into a local-first, cross-platform desktop workspace with sessions, project files, an embedded browser, MCP, skills, and WeChat/Telegram/Lark messaging.
- Source repo
- DLYZZT/pi-desktop
- Stars
- ★ 321
- Last updated
- 12d ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 52/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformOpenAI API
- You'll need
- Typical use
- A Pi CLI user moving to a GUI: install the desktop app and reuse existing sessions and credentials from
~/.pi/agent/with zero migration. - Main limitation
- Windows 32-bit, Windows ARM64, and Windows Server are unsupported; managed background processes additionally require macOS, Linux, or Windows 11 x64.
- Source review
- 52/100 · Major gaps
What does this agent do, and when should you use it?
Pi Agent Desktop is an Electron desktop workspace for the Pi Coding Agent — local-first, with no internal servers, shipped for macOS, Windows x64, and Linux x64. It uses a three-process architecture: the Electron main process owns windows, tray, the embedded browser, and updates; a dedicated Agent Host utilityProcess runs the Pi Agent; a React 19 renderer talks to the Host only through typed IPC. The app covers session management, project files with Git Worktree support, an embedded Chromium browser, MCP services, Skills/Plugins, Auto virtual-model routing, and Codemode image generation and decision models. Sessions and configuration live in ~/.pi/agent/, so it coexists with the Pi CLI with no migration. Data stays on the machine by default; how model requests are processed depends on the provider you configure.
The app reads sessions and model config from ~/.pi/agent/, runs Pi Coding Agent 1.4.0 inside an Agent Host utilityProcess, and renders streaming replies, tool-call execution trees, and context-compaction state in a React 19 UI. Users manage Git branches and worktrees, browse multi-tab project files, and preview Markdown/Mermaid/KaTeX/Word documents; the Agent drives a Main-owned WebContentsView under separate Browser read/interact grants to navigate, take structured page snapshots, screenshot, click, and type. Managed background processes keep Vite, Storybook, Flask, and similar dev servers running via explicit process_* tools (POSIX process groups on macOS/Linux; a Rust helper plus Job Object on Windows x64), with a Processes panel showing redacted logs, readiness, and loopback endpoints. An MCP panel manages stdio/Streamable HTTP servers, OAuth login, and tool discovery; the Auto virtual model routes each new prompt between fast and strong models by thinking level or a decision model. WeChat, Telegram, and Lark channels exchange text, images, files, and voice via outbound long polling/WebSocket, mapped to independent or bound Pi Sessions.
- A Pi CLI user moving to a GUI: install the desktop app and reuse existing sessions and credentials from
~/.pi/agent/with zero migration. - Front-end work where the Agent should verify its own changes in a real browser: run a Vite dev server as a managed process and let the Agent drive the embedded browser against localhost, taking snapshots and screenshots.
- Continuing coding tasks from your phone while away: pair a WeChat, Telegram, or Lark private chat and route external messages into a desktop Pi Session.
- Teams wiring custom MCP tools and resources into coding sessions: add stdio/HTTP servers in settings, log in via OAuth, and authorize tools per session.
- Daily coding where you want cost-aware model switching: enable the Auto virtual model to route each prompt between configured fast and strong models.
How do you install or deploy this agent?
For everyday use, download the v0.4.3 installer (macOS Apple Silicon/Intel, Windows x64, Linux x64 AppImage); after installing, just configure a model provider — no separate Node.js or npm required. To run from source you need Node.js 22.19+ and npm:
git clone https://github.com/DLYZZT/pi-desktop.git
cd pi-desktop
npm ci
npm run devTo build installers:
npm run distRequirements: macOS 12+, Windows 10/11 64-bit (x64), or 64-bit Linux (modern glibc + desktop session); no Windows x86/ARM64 installers are provided.
How do you use this agent?
- Launch the app and configure API keys, subscriptions, or OAuth per provider under Settings → Models (existing
~/.pi/agent/config is picked up). - Select a project directory, create a session, and start coding requests; use
@file references, slash commands, and image attachments. - Enable Codemode, tool search, or the Full Access preset from the session tools menu; first browser or sensitive operations ask for per-session confirmation.
- Optional: configure Auto under Settings → Models → Auto Routing (fast/strong/decision models) and pick Auto in the chat model menu.
- Optional: connect MCP servers, Skills, Plugins, and WeChat/Telegram/Lark channels (WeChat QR login, Telegram BotFather token, Lark QR or App ID/Secret).
What are this agent's strengths and limitations?
- Local-first with zero internal servers: sessions stay in
~/.pi/agent/and coexist with the Pi CLI; the renderer runs with Electron sandbox, strict CSP, and a hard-coded GitHub Release update config. - Unusually complete scope: MCP OAuth, Codemode/tool search, Auto routing, managed background processes (with fail-closed integrity checks on the Windows x64 Rust helper + Job Object), and three messaging platforms in one app.
- Engineering rigor: typed IPC contracts, architecture-boundary checks, execution-history recovery tests, macOS signing/notarization, and a three-platform CI release matrix.
- Windows 32-bit, Windows ARM64, and Windows Server are unsupported; managed background processes additionally require macOS, Linux, or Windows 11 x64.
- The app is free but needs model provider accounts or API keys; some features (e.g., the OpenAI decision interface) explicitly require an API key — ChatGPT subscription login does not provide it.
- WeChat channel limits: group chats are not yet available and remote tool permissions are not granted by default; private-network protection is explicitly labeled best-effort.
- Managed processes are lifecycle control, not a container or sandbox: child processes have the same local file, network, and environment permissions as Agent Bash.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pi Agent Desktop This agent | 52 · Major gaps | — | ★ 321 | 12d ago | TypeScript | OpenAI API |
| iPolloWork | 44 · Major gaps | Desktop appFree + model costs | ★ 7.4k | 1d ago | TypeScript | — |
| Synara | 52 · Major gaps | Desktop appFree + model costs | ★ 2.2k | today | TypeScript | Codex · Claude Code |
| wsp | 39 · Major gaps | Desktop appFree + model costs | ★ 14 | today | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
README documents Electron sandbox, strict CSP, typed IPC, browser/process tools off by default, first-use prompts, and policy-revision validation, which are concrete least-privilege and confirmation designs; however these are documentation assertions without source code shown, so least_privilege and user_confirmation score 2 not 3. Data flow transparency is decent (local ~/.pi/agent storage, no internal TCP service, outbound-only polling/WebSocket) at 2. Sensitive data handling only broadly mentions tools not accepting/returning cookies and credential replacement confirmation, lacking key storage and log redaction evidence, deducted to 1. Dependency security has check:dependencies, cargo audit/deny, SBOM, and hash verification gates, but no actual audit results, scored 2. External effects include process management, browser write replay, and IM channels with real side effects, only promised via docs, scored 1. Rollback only mentions Windows NSIS upgrade rollback E2E and process cleanup, lacking general rollback/undo, scored 1. Source attribution has Apache-2.0 and author field, but publisher identity is unverified, scored 1.
README, package.json, and CI workflow agree on version 0.4.3, Node 22.19, Electron 43, and Pi 1.4.0, self-consistency scored 2. Dependency availability is supported by npm ci, lockfile, pinned versions, and multi-platform CI matrix, scored 2. Failure messages only mention crash reports, diagnostic exports, and fail-closed concepts without concrete error copy, scored 1.
Targets ordinary desktop users and developers with sufficient scenario description (2). Capability boundaries clearly separate browser, process, Herdr, and IM authorization with defaults off (2). Trigger precision describes Auto routing, tool discovery, and slash commands but lacks precise decision evidence, scored 1. Environment fit lists macOS/Windows/Linux versions and unsupported items, scored 2.
Information architecture is clear with TOC, screenshots, and architecture diagram (2). Install notes include download and source-run steps (2). Naming is stable with consistent product and package names (2). Examples and FAQ are thin, only a command table, scored 1. Known limitations are fairly thorough (unsupported platforms, Herdr lacking agent.stop, best-effort private-network protection) (2). License is full Apache-2.0 text (2). Versioning/changelog only links to Releases without embedded changelog, scored 1. Maintenance responsibility is only an author field with unverified publisher, scored 1.
Output usability covers sessions, files, browser, and process panels as a complete workspace (2). Marginal value over Pi CLI is clear via desktop integration and multi-channel support (2). Cost-benefit has heavy dependencies, large Electron footprint, and multi-model/toolchain setup with insufficient trade-off evidence, scored 1.
Claims trace to README and CI scripts but are mostly documentation assertions, scored 1. Cross-source corroboration is limited; README, package.json, and workflow partially agree but do not cover all claims, scored 1. Fact/inference separation is average with some marketing-style capability descriptions, scored 1.
- Publisher identity is unverified; maintainer and update-source trust cannot be confirmed.
- Security and permission claims come mainly from README documentation without source-level evidence; static review cannot verify actual implementation.
- Process management, browser write replay, and IM channels have real external side effects; review confirmation and rollback mechanisms yourself.
- Dependencies are heavy with Electron and multi-platform native components; watch supply chain and footprint costs.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
v0.4.3 更新日志 本次版本将内置 Pi Coding Agent 升级到 1.4.0，改进长会话压缩、工具调用和多会话代码编排，补充模型配置兼容提示，并精简普通服务商的 API Key 配置入口。 修复与改进 - Pi 运行时升级：从 1.2.0 升级到 1.4.0，包含 1.3.0 与 1.4.0 的累计更新。统一固定相关运行时包版本，并完善模型配置 schema、代码编排 worker 和运行资源检查，减少依赖混版及打包资源缺失问题。 - 长会话与摘要可靠性：上下文压缩和分支摘要采用模型的输出限制，改善长推理占满旧摘要预算导致的失败；分割轮次的摘要也会保留手动压缩指令。修复回复被输出上限截断后，工具调用与结果不匹配导致后续请求持续失败的问题。 - 模型切换与供应商兼容：切换模型时，不再将前一个模型的思考内容转换为正文发送给新模型，原始会话记录保持不变。同步上游模型目录、推理档位和请求转换修复，改善空白工具输出、错误结果图片及部分临时服务错误的处理。 - 多会话代码编排：Codemode 在进程内 worker 被占满时等待空闲名额，改善多个会话并行调用时立即失败的问题。等待计入脚本超时预算，取消和超时后继续保持执行记录与状态可追溯。 …View on GitHub ↗ -
Release notes excerpt
v0.4.2 更新日志 本次版本新增自定义服务商模型发现，重新整理自定义模型设置，修复推理强度映射与聊天菜单不一致的问题，并完善服务商重命名后的模型启用、Auto 路由和已有会话恢复。 修复与改进 - 自动获取模型列表：自定义服务商支持点击“获取模型列表”，使用当前地址、API Key 和请求头从兼容 OpenAI 的 /models 接口读取模型。兼容根地址、/v1、自定义路径前缀和完整模型列表地址；获取结果合并到编辑草稿，保留已有模型设置，不重复添加相同模型。 - 自定义模型设置体验：将服务商设置整理为“连接与发现”“聊天模型”“高级”三个分区，显示已启用数量，支持搜索服务商、模型名称和完整模型 ID。高级 JSON、费用等配置默认折叠，补充未保存状态与操作提示，减少长列表和复杂字段带来的干扰。 - 模型启用与聊天菜单：明确区分模型定义和聊天显示选择。新增模型保存后，可在“聊天模型”中启用；启用选择即时保存，并同步更新聊天模型菜单。获取模型列表不会更改已有的启用选择。 …View on GitHub ↗ -
Release notes excerpt
v0.4.1 更新日志 本次版本将内置 Pi Coding Agent 从 1.1.0 升级到 1.2.0，新增 Windows PowerShell 支持和默认 Agent Shell 设置，完善模型配置恢复、MCP 工具权限与渠道附件处理，并修复设置面板首次打开时的白屏和加载期间的焦点问题。 修复与改进 - Pi 1.2.0 升级：同步升级 Pi 运行时及相关组件，适配工具元数据、回合准备和扩展处理流程。修复新工具元数据导致工具列表无法传回界面的问题，界面只接收展示所需字段，不再携带扩展的本机绝对路径等内部信息。 - Windows PowerShell 支持：支持 Windows PowerShell 5.1 和 PowerShell 7，可在“设置 → 通用”选择新会话默认使用 Bash 或 PowerShell。自动检测优先使用可用的 PowerShell 7，也可在开发工具中指定可执行文件；安装或调整路径后可刷新工具状态。已有会话保留原有执行器选择。 - PowerShell 执行可靠性：改进中文、Emoji、多行脚本、引号和标准输出／错误输出的处理，修复输出分块交错造成的 UTF-8 字符损坏。完善停止、超时、进程树清理和退出状态处理；过长命令在执行前明确报错，避免被截断后执行。 …View on GitHub ↗