Percho: an Electron shell around the Pi coding agent, with the CLI's config directory

The problem is not the agent, it is the approval loop

Terminal coding agents are good at editing files and bad at telling you what they are about to do. The Pi CLI runs the agent loop and prints tool calls as scrolling text, which means approving a write to the wrong path is a matter of reading fast enough. Percho's answer is a dock of visual permission gates backed by a per-tool rule engine, so each tool call is a card you approve or deny before it runs. The README frames the whole project as being for people who prefer a GUI over a TUI, and that is the honest scope. It is not trying to be a better agent. It is trying to make the same agent's decisions legible. The secondary audience is anyone already invested in Pi's extension model: TypeScript extensions, skills and prompt templates installed for the CLI are stated to work in Percho, including project-local ones, which arrive behind a trust prompt before they load.

Embedding the SDK in the Electron main process, not forking it

The architectural claim in the README is specific and checkable: Percho embeds the official Pi SDK, the npm package @earendil-works/pi-coding-agent, in the Electron main process, and the README states plainly that it is not a fork and not a reimplementation. The repository layout backs the separation up. It is an npm workspaces monorepo with three packages: packages/shared holds IPC contracts, packages/backend is described as the only place that imports the Pi SDK, and packages/desktop holds the Electron plus React 19 plus Tailwind 4 plus Zustand renderer. That constraint matters more than it looks. If the SDK import is confined to one package, the GUI can be rewritten or the renderer swapped without touching the agent integration, and upgrading Pi means bumping one dependency rather than rebasing a fork. The data flow follows from the same design: the main process talks to the SDK, the shared package defines the IPC surface, and the renderer never sees the agent directly. The cost of this arrangement is that anything Pi's SDK does not expose is not available to the GUI, no matter how much the UI would like it.

Shared config is the strongest reason to pick Percho over a standalone client

Percho reads the same ~/.pi/agent/ directory as the CLI, and the README says sessions, auth and model settings carry over, so a session started in the terminal can be continued in the GUI. That one property rules out most of the usual migration friction. Providers are configured the same way: subscriptions for Claude Pro/Max, ChatGPT Plus/Pro Codex and GitHub Copilot are logged in through an in-app OAuth flow, while Anthropic, OpenAI, Gemini, DeepSeek and Bedrock take API keys, with custom providers and base-URL overrides for relay gateways. The configuration section is explicit that keys are never stored in the repository or written into the app bundle. Instead ~/.pi/agent/models.json references environment variables such as $AI_OPS_API_KEY, and the key itself stays in your shell environment. If you already run the Pi CLI, the README's position is that your existing setup just works. That is a claim about file layout, and it is the first thing worth confirming on your own machine before adopting anything.

Getting it running: installers, then npm run dev

There are two paths and they are documented separately. For end users, prebuilt installers are published on the Releases page: percho-mac-arm64.dmg, percho-mac-x64.dmg, and on Windows either percho-windows-x64.exe as an installer or percho-windows-x64.zip. The macOS builds are ad-hoc signed with no Developer ID certificate, so the README warns that the first launch may show a Gatekeeper message about Apple not being able to verify the app is free from malware. The documented workarounds are System Settings, Privacy & Security, scroll to the bottom, Open Anyway, or from Terminal, xattr -cr "/Applications/Percho.app". On Windows the equivalent is More info then Run anyway when SmartScreen appears. For developers the prerequisites are Node.js >= 22.19, then npm install followed by npm run dev. The other scripts listed are npm run typecheck, test, lint, build and dist. One environment note appears in the README: if you are in China and the Electron binary download stalls, set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ before installing.

The update path is the weakest part of the packaging story

Updates are checked in-app. On Windows they download and install in place, described as click download then restart. On macOS the ad-hoc signed build cannot self-install, so the app opens the Releases page instead, and a freshly downloaded version hits Gatekeeper again. Read that sequence carefully, because it is not a one-time onboarding annoyance. Every macOS update repeats the manual download, the Gatekeeper bypass and the confirmation. For a tool that ships point releases as often as this one does, with v0.5.4, v0.5.5 and v0.5.6 landing within roughly two weeks of each other, that is a recurring tax. The platform matrix is also narrow: the README's own badge lists macOS and Windows only, with no Linux build mentioned anywhere in the download table. If you work on Linux, this is not a tool you can evaluate on your primary machine at all.

Context evaporation and subagents are the parts worth scrutinising

Two features deserve more scepticism than the README's bullet list invites. Context evaporation is described as on by default, with stale tool outputs aging into compact stubs to keep long sessions within budget. That is a real mechanism for a real problem, and it is also a lossy transformation applied without asking. The README does not state whether the original tool output is recoverable after it has been stubbed, nor whether the threshold is configurable. If you are debugging an agent that made a decision twenty turns ago based on output that has since been compacted, you will want to know the answer before you rely on it. The subagent system is more transparent by design: a built-in scout plus your own agent definitions, parallel task fan-outs, and run cards you can click to inspect the sub-session read-only. Read-only inspection is the right default for fan-outs, but it also means you cannot intervene in a sub-session that has gone wrong. You can watch it, and you can read it afterwards.

What Percho is not, and what to compare it against

Percho is not a hosted agent and not a new runtime. The README states it is a community project, not built by or affiliated with the Pi team at earendil-works. That disclaimer is doing real work: if the Pi SDK changes in a way the GUI does not accommodate, the fix belongs to Jaxton07, not to earendil-works. The natural comparison is the Pi CLI itself, and the difference is narrower than the marketing suggests. The CLI gives you the same engine, the same extension loading, the same ~/.pi/agent/ directory and the same providers, with no Electron process, no installer, no Gatekeeper prompt and no platform restriction. What the CLI does not give you is the visual layer: per-call approval cards, draggable multi-session tabs with an optional session rail, per-session composer drafts, a follow-up queue with undo, a todo panel, a per-turn diff sidebar, slash-command and @-file completion, and a LAN observer that lets you watch a session read-only from a phone or tablet browser via QR code. Those are interface decisions, not engine decisions. Anyone who is comfortable in a terminal and does not need the approval dock should stay on the CLI and skip the packaging overhead entirely.

Licence, maintenance and what to verify before committing

Percho is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. Note that this covers Percho's own source. The Pi SDK it depends on is a separate package with its own terms, and the repository does not restate them, so check the @earendil-works/pi-coding-agent licence separately if that matters to your organisation. Nothing here is legal advice. On maintenance cost, the visible signals are a monorepo with typecheck, test, lint, build and dist scripts plus a CI workflow, frequent point releases, and a CONTRIBUTING.md the README points to for the full guide. What the material does not tell you is how the project behaves when the upstream SDK makes a breaking change, which is the maintenance question that actually matters for a wrapper. Verify that first, then verify the trust prompt fires on a project-local extension and that your models.json resolves keys from the environment rather than embedding them.

Editorial conclusion

Adopt Percho if you already run the Pi CLI and want per-tool approval gates, parallel subagents and draggable session tabs without giving up your existing ~/.pi/agent/ sessions and model settings. Skip it if you are on Linux, if you need a signed and notarized macOS app that updates itself, or if you want an agent runtime that is independent of the Pi project. Before trusting it with a real repository, verify three things: that the trust prompt appears when a project-local extension is loaded, that ~/.pi/agent/models.json resolves your API keys from environment variables rather than storing them, and that the LAN observer is off or scoped to a network you control.

Official sources

1. Jaxton07/percho on GitHub
2. License: MIT
3. Project website
4. README
5. Releases