WINDOWS 10+ · ELECTRON · REACT 19 · TYPESCRIPT · MIT
很多 agent 客户端，
这一个跑在你的 pi 上。There are many agent clients —
this one runs on your own pi.
PiDesk 是开源 coding agent
pi
的 Windows 桌面客户端。它不重新实现 agent：pi 以 --mode rpc 子进程运行，PiDesk
通过 JSONL over stdio 驱动它。会话历史始终是 pi 原生的 JSONL 文件——终端里的 pi
和界面里的 pi，读的是同一份数据。PiDesk is a Windows desktop client for
pi, the open-source coding agent. It does not reimplement the agent: pi runs as a
--mode rpc child process that PiDesk drives over JSONL stdio. Session history
stays in pi's native JSONL files — the pi in your terminal and the pi in this UI read the
same data.
3 STEPS
$ npm install -g @earendil-works/pi-coding-agent # ① 装 pi CLI① install the pi CLI$# ② 从 Releases 下载 PiDesk 安装包（附 SHA-256）② grab the PiDesk installer from Releases (SHA-256 included)$# ③ 设置里指向 pi 可执行文件，新建任务③ point Settings at the pi executable, start a task
PiDesk 只做客户端该做的事PiDesk only does what a client should do
agent 循环、模型鉴权、上下文压缩、工具执行，全部发生在 pi 进程里。PiDesk
提供的是桌面工作台：把事件流渲染成可读的文档，把项目、终端、浏览器和 git
变更摆在旁边，把 pi 的扩展生态装进面板。The agent loop, model auth, compaction and tool execution all happen inside the pi
process. PiDesk provides the desktop workbench: rendering the event stream as a readable
document, keeping the project, terminal, browser and git changes alongside it, and
hosting pi's extension ecosystem in panels.
~/.pi · JSONL会话历史始终是 pi 原生文件Session history stays in pi's own files
PiDesk 不复制会话正文，也不做二次同步；只另存标题、归档、置顶这类标记。MCP 配置同样写在 pi 的用户级
mcp.json，与 CLI 共享一份。PiDesk copies no transcript and does no second sync; it only keeps markers such as
titles, archive flags and pins. MCP config lives in pi's user-level
mcp.json, shared with the CLI.
卸载 PiDesk，会话文件还在，终端里接着跑。Uninstall PiDesk and your sessions survive in the terminal.
pi 升级协议，PiDesk 不需要同步实现一份。When pi evolves the protocol, no second implementation to chase.
没有 PiDesk 账号，也没有 PiDesk 的模型额度。No PiDesk account, and no PiDesk model quota.
默认 8 个进程同时存活，1–32 可调；切换不杀进程，超限时新会话启动失败而不是挤掉旧的8 live processes by default, tunable from 1 to 32; switching never kills one, and hitting the ceiling refuses the new session instead of evicting an old one
扩展注册界面，pi 本体零改动Extensions ship UI, pi itself untouched
§ 03
文档流，而不是聊天气泡A document flow, not chat bubbles
AI 回复按 Markdown 文档流渲染：GFM 表格、编号列表、行内 code 芯片、代码块一键复制。工具调用压成一行紧凑状态行，连续调用自动折叠成「已运行 2
条命令」这样的摘要头；思考过程默认收成一行，展开是弱化排版的 Markdown。长回复要能读、能扫、能引用。Replies render as a Markdown document: GFM tables, numbered lists, inline code chips,
one-click code blocks. Tool calls collapse into compact status rows — consecutive ones group
into a "Ran 2 commands" summary header. Thinking defaults to a single line and expands into
muted Markdown. A long answer should be readable, scannable and quotable.
流式渲染Streaming render会话推送为约 32ms 合批的事件流，渲染层按 sessionId 路由，多会话互不串台。Session events are batched at ~32ms and routed by sessionId, so parallel chats never bleed into each other.
@ 文件引用与附件@-references & attachments原子化 token + 只读文件芯片，支持图片粘贴 / 拖放与任意文件附件。Atomic tokens plus read-only file chips; paste or drop images, attach any file.
问题导航分段栏Question rail每条提问一个跳转锚点，几十轮之后还能一步回到那一问。One anchor per question — jump straight back after fifty turns.
上下文用量Context usage输入框旁常驻一个浮层：已用百分比与 34.3K / 1.0M。A persistent chip by the composer: used percentage plus 34.3K / 1.0M.
本轮文件编辑汇总Per-turn file edits列出这一轮动了哪些文件，撤销与审阅都在同一行。Shows which files this turn touched, with undo and review on the same row.
导出成 MarkdownMarkdown export整篇会话可存成 .md：正文按原顺序排，思考与工具调用折成折叠块，图片只记数量不落盘。Save the whole transcript as .md: bodies in original order, thinking and tool calls folded into details blocks, images counted rather than embedded.
访问模式Access modes完全访问 / 计划模式，扩展可通过 SDK 注册自定义模式。Full access / plan mode, and extensions can register their own via the SDK.
§ 04
会话区之外，还有四块面板Four panels around the session
都是真组件，不是 iframe 占位：node-pty 起的真终端、WebContentsView 内嵌的真
Chromium、读 git working tree 的真 diff。Real components, not iframe placeholders: a real terminal on node-pty, a real
embedded Chromium, a real git working-tree diff.
面板 01 · 文件Panel 01 · Files
文件树与只读预览
File tree & read-only preview
项目文件树 + Shiki 语法高亮预览，模糊搜索快速打开（Enter 打开首个匹配）。预览只读，改文件交给 agent。Project tree plus a Shiki-highlighted preview, with fuzzy quick-open. The preview is read-only — edits belong to the agent.
面板 02 · 终端Panel 02 · Terminal
多 Tab 真终端
Multi-tab real terminal
node-pty + xterm，可左右分屏，cwd 跟随当前项目。agent 跑 npm test，你在旁边看同一份输出。node-pty + xterm with side-by-side splits, cwd bound to the project. The agent runs npm test; you watch the same output.
面板 03 · 浏览器Panel 03 · Browser
内嵌 Chromium 与元素拾取
Embedded Chromium & element picking
导入浏览器登录态（Cookie）；拾取模式悬停高亮、点选展开检查器，按 Enter 把元素送进对话栏；样式可热改。Import your cookie session; hover-highlight and select in pick mode, inspect the element, then press Enter to drop it into the composer. Styles hot-reload.
面板 04 · 审查Panel 04 · Review
基于 git 的变更审查
Git-based review
working tree 变更列表 + 逐行 diff，浮窗或侧栏停靠，看完直接提交 / 暂存 / 推送。Working-tree change list plus line-by-line diff, docked or floating, with commit / stage / push at the bottom.
Fig. 03agent 跑 npm test，你在同一块面板里看输出The agent runs npm test; you read the same outputFig. 04变更列表点进去就是逐行 diffAny row in the change list opens its diff
§ 05
pi 的生态，装进面板里pi's ecosystem, hosted in a panel
PiDesk 不制造生态，只做生态的宿主：管理 pi packages、管理 MCP 服务器、把扩展自定义界面渲染到八个槽位上。PiDesk doesn't invent an ecosystem, it hosts one: manage pi packages, manage MCP servers, and render extension-authored UI into eight slots.
MCP 服务器集中管理MCP server management配置增删改、状态探测、会话热重载；配置写在 pi 的用户级 mcp.json，与 CLI 共享。Edit configs, probe status, hot-reload into running sessions — all in pi's user-level mcp.json, shared with the CLI.
MCP 市场MCP market官方注册表搜索 + 精选清单一键预填，不用手抄 JSON。Official registry search plus curated one-click templates, so you never hand-type JSON.
会话内承接In-conversation renderingmcp__* 工具调用与结果按同一套摘要行渲染，摘要头显示「已调用 1 次」。mcp__* calls render with the same status rows, headed by a "called once" summary.
定时任务与用量统计Scheduled tasks & usage按天 / 按月趋势 + 按模型明细的用量卡片，定时任务复用同一套会话引擎。Daily / monthly trends and per-model breakdowns; scheduled tasks reuse the same session engine.
可序列化的 View 协议 + 宿主能力协商 + 软降级。八个挂载槽位：A serializable View protocol with capability negotiation and graceful degradation. Eight placement slots:
modal
stream
widget
panel
sidebar
header
settings
access-mode
Fig. 08会话区承接 MCP 调用：摘要头 + codemode 脚本行 + 工具结果MCP call in the session: summary header + codemode script row + result
§ 06
一个 Windows 应用该有的样子What a Windows app should feel like
中英双语、亮暗主题Bilingual UI, light & darkzh-CN / en-US 界面，亮暗主题跟随系统或手动切换，自定义标题栏与系统托盘。zh-CN / en-US, theme follows the system or switches by hand, custom title bar and tray.
可重绑快捷键与命令面板Rebindable shortcuts & command palette面板、导航、会话切换这些动作都能在设置里改键；命令面板一个入口搜命令、会话、文件与 git 变更。Panels, navigation and session switching are all rebindable in Settings; one palette entry searches commands, sessions, files and git changes.
桌面通知与分场景提示音Toasts & scenario soundsWindows 原生 toast：任务跑完、需要你回答、出错了，各有各的提示音。Native Windows toasts — run finished, input needed, failed — each with its own sound.
GitHub 登录与设置同步GitHub login & settings sync设置写进你的 Gist，换台机器登录就能拉回来。这不是账号体系：模型鉴权仍然由 pi 负责。Settings sync through your own gist, so a second machine picks them up. This is not an account system — pi still owns model auth.
应用内自动更新In-app auto-update从 GitHub Releases 检查并安装更新，安装包附 SHA-256 校验和。Checks and installs from GitHub Releases; every installer ships with a SHA-256 checksum.
Fig. 09亮色主题，同一构图Light theme, same layout
Fig. 10设置 → 外观Settings → AppearanceFig. 11设置 → 配置：pi 可执行文件与版本探测Settings → Config: pi executable and version probe
§ 07
看两段真操作Two real walkthroughs
录自开发实例，没有后期合成的假数据。Captured from a running dev build — no staged mockups.
25.5s · 1920×1200
MCP 全流程
MCP end to end
市场搜索 → 表单添加 → 热重载进正在跑的会话 → 会话区承接 mcp__* 调用。Market search → add via form → hot-reload into a live session → mcp__* call in the transcript.
17.3s · 1920×1200
元素拾取进对话
Pick an element into the chat
内嵌浏览器加载本地报表页 → 悬停高亮 → 点选展开检查器 → 按 Enter，元素芯片进输入框。Load a local page in the embedded browser → hover highlight → select and inspect → press Enter, and the element lands in the composer.
§ 08
我们刻意没做的六件事Six things we deliberately didn't build
客户端不该变成第二个 agent。下面每一条都是「本来可以做，但做了就会和 pi 抢职责」。A client should not become a second agent. Each of these was buildable — and each would have competed with pi for the same job.
No会话正文副本a copy of the transcript
正文始终是 pi 原生 JSONL。PiDesk 只另存标题、归档、置顶这类标记，外加整篇导出成 Markdown 的能力——没有数据库，也没有两份数据谁为准的问题。Message bodies stay in pi's native JSONL. PiDesk keeps only markers such as titles, archive flags and pins, plus a whole-session Markdown export — no database, and no question of which copy wins.
No内置 pibundled pi
安装包里没有 agent。你在设置里指向本机的 pi 可执行文件，PiDesk 探测版本并启动它；MCP 配置也共用 pi 那一份。No agent in the installer. You point PiDesk at your local pi executable; it probes the version and launches it, and the MCP config is shared.
No账号体系account system
模型鉴权由 pi 自身配置承担。GitHub 登录只用来同步设置，不登录也完全能用。Model auth stays in pi's own config. GitHub login only syncs settings; skip it and everything still works.
No聊天气泡 UIchat bubbles
回复是文档流。气泡把一次 200 行的回答切成 20 个色块，而 agent 的输出本来就是文档。Replies are a document flow. Bubbles chop a 200-line answer into 20 colored blocks, and agent output was always a document.
No重造 agent 能力reinvented agent features
子代理、权限门、沙箱这些属于 pi 的扩展生态。PiDesk 负责把它们渲染出来，并让扩展通过 SDK 注册视图与访问模式。Sub-agents, permission gates and sandboxing belong to pi's extension ecosystem. PiDesk renders them and lets extensions register views and access modes through the SDK.
No跨平台cross-platform
只做 Windows 10/11。省下的预算全花在桌面集成上：托盘、原生通知、分场景提示音、自动更新。Windows 10/11 only. The saved budget went into desktop integration: tray, native toasts, scenario sounds, auto-update.
§ 09
开始使用Get started
01
装好 pi CLI
Install the pi CLI
模型鉴权在 pi 里配好，PiDesk 不管账号。Configure model auth in pi; PiDesk never touches accounts.
npm
$ npm install -g @earendil-works/pi-coding-agent
02
下载安装包
Download the installer
NSIS 安装包，Release 附 SHA-256 校验和。An NSIS installer, with SHA-256 checksums on the release.
