PI-Desktop: a local-first desktop workspace for AI coding agents

What PI-Desktop is for

Most coding agents arrive attached to something else: a terminal, an editor extension, or a hosted service you do not control. PI-Desktop takes the opposite position. It is a standalone desktop application whose only job is to host coding agents, projects, models, tools, and long-running sessions in one window.

The README frames it as "a workspace of their own" for agents, and the target user is fairly narrow. You are expected to have a local repository, your own model credentials, and a willingness to supervise what the agent does. The project states plainly that there is "No PI-Desktop account. No mandatory relay. No editor lock-in." That is a design commitment, not a feature list: nothing routes through a PI-Desktop server, and the app does not assume you also use a particular editor.

If your work is one file at a time in one editor, this is more machinery than you need. It starts to make sense when you juggle several repositories, want to switch models per session, and want the agent's file edits and command output visible in the same place you approve them.

Electron shell, Rust host core, plugin surfaces

The repository layout tells you most of the architecture. There are `apps/`, `crates/`, `packages/`, and `examples/` directories at the top level, plus a pnpm workspace and a Cargo workspace. The root `package.json` describes the project as a "Local-first AI coding agent desktop client" and defines build scripts that split the two halves: `build:js` runs the pnpm recursive build, while `build:host` runs `cargo build --release -p host-core`. The Cargo workspace has exactly one member, `crates/host-core`, licensed `LGPL-3.0-or-later`.

So the data flow is roughly: the Electron front end renders projects, conversations, reviews, files, previews, notifications, and extensions; the Rust host core does the privileged work; and the agent runtime sits behind a permission layer. The README says privileged actions pass through that layer, and that you review diffs and inspect command output before deciding how much autonomy a session gets.

The extension story is the part worth watching. Plugins can contribute tools, commands, panels, themes, services, skills, and what the README calls "new workspace experiences." Skills, MCP servers, and Subagents are separate extension points. The `examples/plugins/` directory exists to show the shape of a plugin. But the README's own Early Preview notice says extension interfaces may continue to evolve, which is the honest way of saying: do not build a large plugin portfolio against this yet.

Installing PI-Desktop and connecting a model

The README points to the GitHub releases page as the download location, and the platform badge lists macOS, Windows, and Linux. There is no package-manager install documented for end users.

If you want to build from source instead, the root `package.json` pins the toolchain. It declares `packageManager: [email protected]` and requires Node `>=22.19.0` and pnpm `>=10`. The full build script chains the JavaScript build with the Rust host build, so you need a working Rust toolchain in addition to Node.

pnpm install
pnpm build
pnpm dev

The `dev` script filters to `@pi-desktop/desktop`, so it starts the desktop app rather than the documentation site. The `build` script runs `pnpm -r --if-present build` followed by `cargo build --release -p host-core`, which is why the first build takes noticeably longer than a pure JavaScript project.

Once the app is open, the README's four-step flow is: open Settings then Model configuration and add a provider and credentials; add a local project directory from the sidebar; pick Agent, Plan, or Goal; then review the result in the Review panel. Providers include OpenAI and Anthropic, OpenAI-compatible APIs, hosted gateways, and local gateways such as Ollama and LM Studio. You can switch models from the Composer without recreating the session.

For the end-to-end smoke test, the repository ships a `.env.example` with three variables, and its comment is explicit that they are used only by that script and that real keys must never be committed:

PI_DESKTOP_TEST_BASE_URL=
PI_DESKTOP_TEST_MODEL=
PI_DESKTOP_TEST_API_KEY=

Running `pnpm test:e2e` invokes `node scripts/e2e-smoke.mjs`, which reads those variables. Leave them empty and the smoke test has nothing to call.

Agent, Plan, and Goal are three different approval gates

The mode selector is the most concrete idea in the project, and it is worth being precise about what each mode does, because the names are easy to misread.

Agent is the default loop. The agent reads files, edits code, runs commands, tests, and iterates, with no extra approval beyond the permission layer that applies in every mode.

Plan is an approval boundary, not a planning assistant. The agent studies the repository and writes an implementation plan that the README calls "frozen" and "immutable." Execution does not begin until you sign off. If you approve a plan and then realize the approach is wrong, the plan itself is not the thing that adapts; you are.

Goal inverts the order. You lock the objective and the acceptance criteria, and the agent decides the route. The README's framing is that you approve the outcome, then the agent chooses the path.

There is a real trade-off here that the README does not dwell on. Plan mode is only as good as the plan the agent produces, and reviewing a frozen plan is a different skill from reviewing a diff. Goal mode gives up the intermediate checkpoint entirely. Neither is a safety mechanism; the permission layer is, and it applies to all three.

Subagents and what long sessions actually cost

Large tasks do not fit in one context window, and PI-Desktop's answer is Subagents. The README lists codebase exploration, multi-file implementation, research and investigation, test analysis, and adversarial review as delegation targets. Each Subagent runs in its own context and reports back to the parent agent.

That is a context-management strategy, not a parallelism claim. The README does not say how many Subagents run at once, how their results are merged, or what happens when two of them touch the same file. The repository does include `test:e2e:subagents` and `test:e2e:subagent-models` scripts, so there is test coverage for the mechanism, but the documentation does not describe conflict handling.

The session features are more fully described. You can manage multiple projects and sessions, pin or archive conversations, branch sessions, queue prompts while an agent is running, reference files with `@`, use slash commands, and search across the application. The README also says streaming responses are checkpointed so interrupted work can survive restarts or runtime failures "whenever possible." That qualifier is doing real work: checkpointing is best-effort, and the README does not document rollback for the cases where it fails.

Limitations, and when a terminal agent is the better tool

The first limitation is stated by the project itself. PI-Desktop is in Early Preview, and the README warns that APIs, extension interfaces, and some desktop behaviors may continue to evolve. If you are evaluating it as a platform to build on, that is the sentence that matters most. Plugin authors are building against a moving target.

The second is the desktop requirement itself. This is an Electron application with a Rust host core. It assumes a graphical environment, a Node 22.19.0 or newer toolchain if you build from source, and a Rust toolchain for the host core. On a headless server, inside a container, or over SSH, that stack is a poor fit. A terminal agent that runs in the shell you are already in will beat it there on every axis.

The third is the model dependency. PI-Desktop does not ship a model. Every session depends on a provider you configured, whether that is a hosted API or a local gateway. If your provider is unreachable, the workspace is a file browser.

The fourth is the licence. The Cargo workspace declares `LGPL-3.0-or-later`, and the repository LICENSE is LGPL-3.0. That is a copyleft licence with specific obligations around modified library code. It is not a blocker for ordinary use, but it is a different proposition from a permissively licensed tool if you intend to redistribute a modified host core.

Where it is simply the wrong tool: if your workflow is one prompt, one patch, one commit, the mode selector, the review panel, and the session manager are overhead you will click past.

How PI-Desktop differs from an editor-embedded agent

The obvious alternative is an agent that lives inside your editor, where the diff, the file tree, and the agent already share a window. That approach wins on proximity. You never leave the file you are editing, and the agent inherits the editor's language server, its keybindings, and its project index.

PI-Desktop trades that proximity for independence. Its stated position is no editor lock-in, which means the same workspace can drive agents across repositories you open in different editors, or in no editor at all. It also means the review surface is the application's own, not the editor's diff view, and the model configuration is per session rather than per editor profile.

The second alternative is a hosted agent service. Those remove setup entirely and give you a managed runtime, at the cost of sending your code to someone else's infrastructure and accepting their model list. PI-Desktop's counter-position is explicit: bring your own model, including local gateways such as Ollama and LM Studio, so the code and the inference can both stay on your machine.

Neither comparison is a clean win. The editor agent is faster to start with. The hosted service is less to maintain. PI-Desktop is for the case where neither of those trade-offs is acceptable.

Maintenance, releases, and upgrade cost

The last push to the repository was on 2026-09-10, and the most recent release is v0.14.6 from the same day, preceded by two release candidates. The version in the root `package.json` and the Cargo workspace is `0.14.8-native.1`, which is ahead of the published release tag. That gap is normal for a project that tags after cutting a build, but it means the version string you see in the source tree is not the version you will find on the releases page.

The release cadence visible in the repository is fast, and the release-candidate tags suggest the project does not treat every build as final. For an Early Preview, that is the expected shape. The practical consequence for adopters is that upgrading is not a background operation. The README warns that desktop behaviors may change, and a release that alters the permission layer or a plugin interface can change what your existing sessions are allowed to do.

The repository ships verification scripts that a cautious upgrader can run before trusting a build: `pnpm test` chains the JavaScript build, the recursive tests, and `cargo test -p host-core`, and there is a long list of `test:e2e:*` scripts covering boot, layout, plan mode, subagents, supervision, and transcript rendering. Running `pnpm test:e2e:boot` after an upgrade is a cheap way to confirm the Electron shell still starts.

On licensing, the LGPL-3.0-or-later declaration in the Cargo workspace applies to the Rust host core. If you only run the application, the obligations are minimal. If you modify and redistribute the host core, the copyleft terms attach to that modified library. This is a description of what the repository declares, not legal advice; check the LICENSE file and your own counsel before redistributing.

Editorial conclusion

Adopt PI-Desktop if you want a coding agent that is not bound to one editor or terminal and you are comfortable running Early Preview software whose plugin and extension interfaces may still change. Skip it if you need a stable extension API today, or if a terminal agent already fits your workflow. Before committing, check that your model provider is reachable from Settings, that the permission layer gates the commands you care about, and that the release you download matches the version you intend to run.

Frequently asked questions

Official sources

1. License: LGPL-3.0
2. Project website
3. README
4. Releases
5. vastsa/PI-Desktop on GitHub