Percho: a desktop shell for the Pi coding agent

It embeds the Pi SDK instead of reimplementing it

The load-bearing claim is a negative one: Percho is neither a fork nor a reimplementation of the Pi coding agent. It embeds the official SDK inside the Electron main process, which means it runs the same engine as the command line client and inherits whatever that engine already does well. That decision shows up structurally rather than only as a slogan. The repository is an npm workspaces monorepo with three packages, and exactly one of them is permitted to import the Pi SDK. A shared package holds the inter-process contracts, and the desktop package carries the interface stack without ever touching the agent SDK directly. Common commands run across the workspaces for type checking, testing, linting, building, and packaging. The result is a boundary you can point at in review: if a feature would require reimplementing agent behaviour rather than configuring it, it belongs in the wrong package by construction. It is also why the project can describe itself as a shell rather than a competing client.

One configuration directory lets a session change surface

The feature that does the most work is not visual. Both clients read the same agent directory under the user's home folder, which means sessions, authentication, and model settings are not per-application state. The readme puts the consequence plainly: start a session in the terminal and continue it in the graphical interface. For anyone who lives in both worlds that is the difference between an app you switch to and a second workspace you maintain. It also raises the stakes on that directory, since anything either client writes is immediately visible to the other, so a malformed session or a half-written setting is a shared problem rather than a private one. The provider configuration follows the same logic, with named subscriptions authenticated through an in-app flow and API keys accepted for several providers, alongside custom providers and base-URL overrides aimed at relay gateways.

Extensions you already installed load here too

Since the engine is shared, the extension surface is shared as well. TypeScript extensions, skills, and prompt templates that were installed for the command line client work in the graphical client, including ones scoped to a single project rather than installed globally. That is a larger claim than it first sounds, because in most desktop wrappers the compatibility stops at the model call, and everything the user has built on top silently fails to load. Here the adaptation path is to configure the agent rather than to fork it, which the readme states as the reason the extension story carries over unchanged. One detail deserves attention rather than skimming. Project-local extensions prompt for trust before loading, which is the correct behaviour for something that can execute code from inside a repository you just opened. It is also the one place where the shared model has a security cost, since the same trust prompt now guards a surface with more ways to reach the filesystem.

Tool calls get a visual approval dock

Permission handling is the feature that most justifies a graphical client, because the failure mode of a terminal agent is approving the wrong thing at speed. Percho puts each tool call into a card you can approve or deny individually from a dock, and behind that sits a per-tool rule engine, so repetitive calls can be governed by policy while unusual ones still get a human decision. The same idea extends off the machine. A LAN companion serves the session to a phone or tablet browser through a QR code, and can optionally surface prompts there, stop generation, and accept allow-once or deny decisions remotely. That is a genuinely useful arrangement when a long agent run outlives your attention span, and it is also the feature with the widest blast radius, since a phone on the same network can now approve tool calls. Worth noting that subagents, parallel task fan-outs, and run cards extend the same idea inward: those cards open a sub-session read-only for inspection rather than granting it control.

Context evaporation is what makes long sessions survive

Long agent sessions fail on budget, not on intelligence, and the mechanism here is called context evaporation and is on by default. Stale tool outputs age into compact stubs rather than sitting in the window forever, which keeps a long session inside its budget instead of degrading until the context window fills. Two adjacent details make it usable rather than merely clever. First, the session workspace supports forking from an assistant turn or from selected context, so a compaction that went wrong is recoverable rather than final. Second, recall lets you pull your own earlier message back into the composer. Around that sits a unified error system, with in-chat error cards offering a single retry, an automatic retry status line, and full-page renderer crash recovery, which is the failure you would otherwise lose the whole session to.

Ad-hoc signing means Gatekeeper on every fresh download

The install instructions are the least polished part of the project and the most worth reading before you start. Builds are ad-hoc signed, with no developer certificate, so macOS treats the app as un-notarised and shows a warning that it cannot verify the app is free from malware. There are two documented ways through: allowing it in the privacy settings pane with Open Anyway, or clearing the extended attribute from a terminal. The update story then compounds it. On Windows, updates download and install in place and SmartScreen prompts for more information before running. On macOS, because the build is ad-hoc signed it cannot self-install at all, so the app sends you to the releases page, and the version you download there trips Gatekeeper once more. On Linux, updates do work in place, but the AppImage must be made executable first and needs the FUSE 2 library on recent Ubuntu releases, since it is no longer preinstalled.

The package version lags the release tags

A detail worth flagging for anyone scripting against this repository: the version field in the package manifest reads a pre-one value while the published releases are in the zero-point-six range, with three tagged inside a single week of September 2026. So the manifest is not the source of truth for what is shipped, and a dependency or automation that reads it will be wrong. The rest of the toolchain is more disciplined. The Node engine floor is declared explicitly and matches the documented prerequisite, the formatter and linter is a single check across the repository, and local development is the usual pair of commands:

npm install
npm run dev

The install step also runs a patch application tool rather than leaving dependency patches to chance. There is also an explicit allow-list for install scripts, naming one Electron version, which is a sensible thing to find in a desktop project. The readme closes with the disclaimer that matters most for expectations: this is a community project, not built by or affiliated with the agent's own team.

Customisation reaches down to desk-pet overlays

The interface layer goes further than reskinning, and the list of extension points is the clearest statement of what the project thinks a desktop shell is for. Tool-call cards can be swapped out wholesale, so the shape of a pending approval is a design decision rather than a fixed component. Overlays can be dropped on top of the window, and two whale-themed companion characters ship built in, which tells you the author considers delight a legitimate feature for a tool people stare at all day. The settings panel itself is extensible through interface plugins, which is a meaningfully deeper hook than allowing a new provider. Alongside that sit a custom background image with an adjustable overlay dimming so text stays readable over it, light, dark, and system theme modes, streaming markdown rendering, image previews, and one-click message copying. One tool deserves separate mention, a built-in image display tool that lets the agent put an image in front of you deliberately, singly or grouped, rather than treating every image in a tool result as something to render and thereby turning a screenshot into noise.

Editorial conclusion

Percho suits someone who likes the Pi agent's engine but works in a window rather than a terminal, since it keeps the same configuration and extensions and adds the approval flow and error recovery that a graphical client can carry better. It is a poorer fit if you need signed and notarised macOS builds, because ad-hoc signing means every fresh download meets Gatekeeper again, and a poor fit if you want to contribute upstream, since the design deliberately avoids forking the agent. Before installing on macOS, know that you will be clearing an unsigned attribute or allowing the app by hand, and if you rely on custom providers, check that your base-URL override behaves the same in both clients.

Frequently asked questions

Official sources

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