pi-agent-desktop README

项目的 README,来自 github.com/abcwyc/pi-agent-desktop。合并为一个 markdown 文件:README.md。

Pi Agent

English | 简体中文

pi-agent-desktop is a local AI agent desktop app for macOS and Windows. It packages the agent capabilities of pi into a standalone, installable application.

Features

Pi Agent light mode

Pi Agent dark mode

⬇️ Download Pi Agent (macOS / Windows)

Repository: abcwyc/pi-agent-desktop

Installation And Usage

Install The Desktop App

Builds are available from GitHub Releases:

Official releases support Macs (Apple Silicon or Intel) running macOS 11 or later, Windows 10/11 x64, and Linux x64 distributions with WebKitGTK 4.1 and GTK 3. The desktop package bundles the Next.js server, the Node.js runtime, and the current Pi SDK, so the local server starts with the app — no separate terminal, Node.js installation, or manually started web server is required.

Installing Pi Agent gives you the agent inside the app, but it does not install a global pi command. If you also want the Pi CLI in your terminal, install it separately by following the pi project instructions.

macOS blocks the first launch: the macOS build is not yet signed with an Apple Developer ID or notarized, so Gatekeeper may say the developer cannot be verified or that the app "is damaged and can't be opened" (Homebrew installs included). Click "Open Anyway" in System Settings › Privacy & Security, or run:

xattr -dr com.apple.quarantine "/Applications/Pi Agent.app"

Before signed auto-updates can be used for the first time, an older build without the updater has to be replaced by manually installing a signed one. Upgrades then happen from Settings.

Use Existing Pi Data

Pi Agent reads Pi's local data directory by default:

~/.pi/agent/

Sessions normally live under:

~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl

If you have used Pi on this machine before, the app picks up your existing sessions, models, and authentication after installation. Set PI_CODING_AGENT_DIR to point at a different Pi agent data directory.

Model keys and session data stay on your machine. The file-browsing API only allows access to the current session, the selected project, and explicitly authorized working directories.

Update Checks And Upgrades

Pi Agent checks the latest stable release of abcwyc/pi-agent-desktop at most once every seven days:

The versioning and upgrade rules are:

  1. The latest stable pi-agent-desktop release is the only source used for update reminders.
  2. The upgrade button in Settings becomes enabled only when the installed desktop app version is older.
  3. When several components need updating, the release automation syncs and verifies them in the order pi → pi-web → pi-agent-desktop.
  4. Nothing patches an individual JavaScript package inside an installed app. The app downloads one complete signed build containing all three components at their latest versions.
  5. The app restarts after installation, so all three components land in the same verified release state at once.

This keeps the components in a desktop install consistent, and avoids the runtime incompatibilities that come from swapping pi or pi-web on their own.

If a new upstream version has been detected but the signed pi-agent-desktop release containing it is not published yet, Settings says that no signed complete build is installable for now. The app never falls back to downloading unsigned files or partially overwriting dependencies.

The full sync, signing, and release configuration is described in Desktop updates and releases.

HTTP Proxy

Turn on Settings › General › Network proxy and enter an address such as http://127.0.0.1:7890 to send this app's outbound requests through an HTTP(S) proxy: model APIs, model lists, sign-in, update checks, and commands the agent or a terminal starts afterwards. Other apps keep their direct connection, so no TUN mode is needed. The change applies immediately; localhost and 127.0.0.1 always bypass the proxy, and Test connection reports whether the proxy works. The setting is stored in ~/.pi/agent/pi-web/settings.json (networkProxy).

When the switch is off, the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables still apply, then httpProxy from pi's settings.json. For example, when starting the dev server from a terminal:

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
npm run dev

Local Development

Requirements

Start The Web Dev Server

npm install
npm run dev

The dev server runs at http://localhost:30141 and does not open a browser. npm run web starts the same loopback server and opens http://127.0.0.1:30141 in the desktop browser after it is ready. From WSL that is the Windows browser. See Web profile.

Do not run next build or npm run build during normal development. They write into .next/ and can disrupt a running dev server; production builds are done by the desktop preparation script or by CI.

Network Exposure (LAN)

npm run dev and npm start listen on 127.0.0.1 only. npm run dev:lan, npm run start:lan and pi-web -H 0.0.0.0 listen on every interface. Pi Agent can run shell commands (the terminal tab and the agent's own tools) and read files as you, so anyone who can reach the port gets the same access. Before using a LAN mode, set a password:

PI_WEB_PASSWORD='choose-a-long-passphrase' npm run dev:lan

With PI_WEB_PASSWORD set, the browser asks for it on first visit and failed attempts are throttled. The connection is still plain HTTP, so put it behind HTTPS or a trusted VPN, and use PI_WEB_ALLOWED_HOSTS (comma-separated) to allow a DNS name other than an IP address. Without a password the launcher refuses to listen beyond loopback; on a network you trust, PI_WEB_ALLOW_UNAUTHENTICATED=1 starts it anyway with a warning. The packaged desktop app is unaffected: it binds to loopback and authenticates the WebView with a per-process token.

Start Desktop Dev Mode

npm run desktop:dev

This starts the existing Next.js dev server and opens it in a native Tauri window, without producing an installer.

Common Checks

# Node tests (identical to the CI sync gate, including components/ tests)
npm test

# TypeScript
node_modules/.bin/tsc --noEmit

# ESLint and the branding protection test
npm run lint

# Divergence from pi-web upstream, split into "styling" and "structural" changes
npm run drift

# Rust/Tauri
cargo fmt --check --manifest-path src-tauri/Cargo.toml
cargo clippy --manifest-path src-tauri/Cargo.toml -- -D warnings

# Verify the bundled components match the latest stable releases
npm run release:verify

release:verify reaches GitHub and requires the bundled pi and pi-web to match their latest stable releases exactly, while also checking the component manifest against the actual dependencies.

Desktop Packaging

npm run desktop:build

The desktop build:

  1. Generates the Next.js standalone server in an isolated directory.
  2. Bundles the Node.js runtime for the current architecture.
  3. Places the server and runtime into the app as Tauri resources.
  4. Produces .app, .dmg, and updater artifacts for Apple Silicon and Intel Macs; an NSIS -setup.exe plus updater artifacts on Windows x64; and a .deb package on Linux x64.

On Linux, the package requires a WebKitGTK 4.1 runtime and GTK 3. It includes the Node.js runtime, so users do not need to install Node.js separately.

Local builds do not register the production updater and cannot accept official updates. Official releases must inject the updater public key through GitHub Actions and sign with the matching private key.

Upstream Sync And Releases

The repository contains two chained automation workflows:

Upstream sync uses a Git merge, so this fork's Pi Agent branding, settings entry points, and upgrade logic survive as local modifications. Merge conflicts stop the workflow, which is the safe failure mode. The genuinely dangerous case is a conflict-free but semantically wrong merge: upstream changed a region this fork also changed, Git merged it cleanly, and the tests still pass. The boundary intersection above exists for exactly that case; the rules are in Ownership boundaries.

A failed sync creates or updates a component-sync-failure issue, so nothing piles up silently.

An official release additionally requires:

Project Structure

app/
  api/                  Next.js APIs: agent, sessions, models, files, update checks
components/             Pages, chat, sidebar, settings, and version notices
hooks/                  Client state: session streams, audio, drag and drop, theme
lib/                    AgentSession, HTTP proxy, session reading, file security, upgrade logic
scripts/                Desktop packaging, component version sync, release verification
src-tauri/
  capabilities/         Tauri permission configuration
  resources/            Desktop resources and the component version manifest
  src/                  Desktop window, local server, and updater registration
.github/workflows/      Daily component sync and desktop release automation
instrumentation.ts     Next.js server-side HTTP proxy initialization

Credits And License

The desktop integration of Pi Agent is provided by pi-agent-desktop; the core capabilities and the web interface come from earendil-works/pi and agegr/pi-web respectively. Thanks to those projects and their contributors.

Code in the root of this repository is under the MIT License in LICENSE. The code and dependencies of the three component projects remain subject to the licenses of their own repositories; keep the corresponding copyright and license notices when copying, modifying, or redistributing.

pi-agent-desktop (abcwyc/pi-agent-desktop)

正在搜索数据库…

这是什么?Pi Agent Desktop 将 “pi” AI 编程智能体打包成独立的桌面应用,支持 macOS、Windows 和 Linux。无需打开终端,也无需配置环境,就能获得类似 Claude Code 的编程助手。
我还需要单独安装 pi CLI 才能使用吗?不需要。桌面安装包内置了 Next.js 服务器、Node.js 运行时和当前版本的 Pi SDK,因此无需手动安装 Node.js,也无需进行终端设置,即可独立运行。不过它不会安装全局的 “pi” 命令;如果你还想在终端中使用,需要另外安装 Pi CLI。
它能在 Intel 芯片的 Mac 上运行吗?macOS 版本有签名吗?不提供 Intel 芯片 Mac 版本,目前只有 Apple 芯片版。macOS 版本尚未完成 Apple 公证,也未使用 Apple Developer ID 签名,因此首次启动时,Gatekeeper 可能会提示无法验证开发者,或者提示应用已损坏。
我的会话和模型密钥存放在哪里?所有数据都保存在本地。应用会读取 Pi 现有的本地数据目录(与 pi CLI 共用),模型密钥和会话数据都留在你的电脑上,不会发送到其他任何地方。
定时任务运行时会发生什么?定时任务会按计划在新会话中运行一个已保存的提示词,计划可以是每小时、每天、每周、自定义 cron 表达式或仅运行一次。即使应用窗口处于隐藏状态,任务也会照常运行。默认只使用只读工具,睡眠唤醒后会补跑一次,并在运行成功或失败时通知你。
升级是怎么进行的?在设置中点击一次升级按钮,即可下载一个完整且已签名的构建包。该包同时包含最新版本的 pi、pi-web 和 pi-agent-desktop,下载完成后会重启应用。升级不会单独修补某个包,也不会回退到未签名的文件。
我可以通过局域网访问这个应用吗?默认只监听 127.0.0.1。像 dev:lan 这样的局域网模式会将应用暴露在所有网络接口上,并且必须设置密码(PIWEBPASSWORD)。因为任何能访问该端口的人,都将获得与你相同的 shell 和文件访问权限。
除了和智能体聊天,我还能管理什么?你可以管理模型、OAuth/API 密钥、技能和插件,切换 Git worktree,浏览项目文件,并在桌面窗口中预览源代码、差异对比、Markdown、图片、音频、PDF 和 DOCX 文件。
作者
abcwyc
大小
21.1 MB
星标
932
时长
3个月
提交 · 90 天