PiDeck: A Desktop Workbench for Multiple pi Agent Sessions

The multi-project session problem PiDeck targets

Running a coding agent in one repository is easy. Running it in six repositories at once is where the bookkeeping starts. Each project has its own session files, its own branch, its own model configuration, and its own terminal. PiDeck's stated audience is developers who want to manage AI coding assistant sessions for several local projects from a desktop window, review session history and Git status in one place, and edit pi configuration graphically rather than by hand.

The README is explicit about what PiDeck is not: it is not a fork of pi. It is a thin Electron shell that launches multiple pi --mode rpc processes. Agent capability comes from pi, session files are written and read by pi, and PiDeck neither reimplements nor hijacks that layer. That boundary matters when you evaluate it. PiDeck adds orchestration, not a new agent runtime. If pi is not installed, there is nothing for the shell to drive.

The scope is wider than pi alone. The README describes a DSH (DeepSeek Harness) backend that runs alongside pi sessions in the same project, plus a separate image-generation backend that speaks the OpenAI-compatible /images/generations endpoint. A project can therefore hold sessions from more than one agent backend, distinguished by pi and DSH badges in the session list and header.

How the Electron shell drives pi and DSH processes

The architecture visible in the documentation is a supervisor pattern. PiDeck starts pi --mode rpc child processes, and the renderer talks to them through the Electron main process. Project management, the conversation view, configuration editing and tool orchestration sit on top of that process layer. Because sessions are pi's own files, importing or resuming them is a matter of pointing at the right directory rather than converting formats.

The DSH integration takes a different route. According to the README, the DSH host is bootstrapped inside a utilityProcess, with no dsh web command, no listening port and no background HTTP server. It starts lazily so application launch is not delayed. Session features that the README lists for DSH include paged history browsing, fork from an anchor point with the fork text returned to the input box, and /compact for context compression. If the application restarts, the original session is restored automatically.

Approval flows are bridged rather than duplicated. DSH approval requests and questions are answered through the same desktop Ask dialog used by pi sessions. That is the sort of detail worth checking in practice, because a bridged approval path is exactly where a desktop shell can diverge from the CLI behaviour underneath it. The README does not document what happens to a pending approval when the window is closed.

Installing PiDeck and opening a first project session

The README points readers at the download section for packaged builds and at a separate quick-start section for running from source. The package metadata shows the standard npm scripts, with dev starting through scripts/dev.js and build chaining code generation steps, local package builds, TypeScript checking and electron-vite. The repository is private in package.json, so this is an application build, not a library you publish.

To run from source, install dependencies and start the development entry point:

npm install
npm run dev

The dev script launches the Electron application. What you should see is the workbench window with the project list; the first thing to do is add a local project directory, which is the unit PiDeck organises everything around.

Configuration lives in pi's own files. The README names models.json, auth.json and settings.json as the files the visual editor manages, and notes that saving restarts the agent as needed for changes to take effect. A minimal shape for a provider entry, based on the file names the README gives, looks like this:

{
  "providers": {
    "example": {
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "sk-..."
    }
  }
}

Treat that snippet as a sketch of the key names the README references, not as a documented schema. The README does not publish a complete models.json example. Use the Provider card and model grid in the settings page to write the file instead of editing it blind, then run the connection test on the provider card. The README notes that model validation no longer treats a configuration fallback as a successful connection, which is a fix worth knowing about if you have seen false positives before.

Where PiDeck stops being the right tool

The project labels itself experimental in the README badge, and the package version is 0.7.6-beta while the newest release listed on the repository is v0.7.4. If your team needs a tool with a stable interface and a predictable upgrade story, that combination is a real constraint rather than a formality. Session management is the kind of feature where a regression is expensive: the README lists rename, duplicate, export to HTML, delete, restart, reload and close agent as session operations, and any of them touching the wrong session is data loss.

The dependency on pi is structural. PiDeck does not provide agent capability of its own, so an environment without a working pi CLI gets a shell with nothing to drive. The README also notes that the Pi CLI version check runs independently of the application updater, which means two upgrade tracks to keep in mind.

Update behaviour differs by platform. The README states that autoDownloadUpdates is on by default, updates are always checked in the background, and the user confirms "restart and install" from the settings page after a download completes. On Windows and Linux the in-package updater handles this; on macOS the application opens the GitHub Release page for a manual install. If you manage macOS machines centrally, that is a manual step per machine.

Configuration editing has its own failure mode. The README says changes to models.json, auth.json and settings.json take effect after restarting the agent as needed. Editing a provider while a session is mid-task and expecting the change to apply immediately is the wrong expectation.

PiDeck against terminal multiplexers and agent-native CLIs

The obvious alternative is not another Electron app but the tooling you already have: tmux or a terminal with split panes, running pi in each project directory. The difference in approach is fundamental. A multiplexer gives you process persistence and keyboard-driven layout, and nothing else. It has no concept of a session list, no Git branch badge, no visual models.json editor and no import path for Codex or Claude sessions. PiDeck trades the terminal's composability for a GUI that knows what a session is.

A second comparison is with the agent CLIs themselves. Codex and Claude keep their own local session stores, and the README positions PiDeck as a reader of those stores: you import Codex and Claude local sessions into a project, they are converted into PiDeck history sessions, and you browse and resume them from there. That is a migration convenience, not a replacement. If your workflow is entirely inside one agent's CLI and you never switch projects, the import feature buys you little.

The third option is simply running pi without a shell. You keep the native session files and the native approval prompts, and you give up the unified view. PiDeck's value is proportional to how many projects and backends you juggle. At one project with one backend, the overhead is not repaid.

Maintenance, licensing and the version-tracking cost

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent and small: v0.7.4 on 2026-09-08, v0.7.3 on 2026-09-03, v0.7.2 on 2026-08-29. That cadence tells you the project moves quickly, and it also tells you that pinning a version is the only way to get a stable surface. The changelog for v0.7.5-beta lists items such as inline citation chip persistence, a sidebar session hover preview, a Git executable path setting, and fixes for dark mode selection colours. These are incremental changes, not architectural ones, which is consistent with a beta line.

PiDeck is MIT licensed, per the README badge and the license field in package.json. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and licence text are retained. That is a statement about the licence text, not legal advice; if you redistribute a modified build, read the LICENSE file in the repository and get your own counsel on notice requirements.

One maintenance cost is easy to underestimate. PiDeck tracks pi compatibility explicitly: the README calls out compatibility with pi 0.84.3 for adaptive context window, maxTokens and thinking-tier behaviour, and the package.json carries a separate dshRuntimeVersion field, currently 0.1.5-rc.1. Two upstream runtimes, two version pins, one application. Budget for that when you plan upgrades, and read CHANGELOG.md or CHANGELOG.zh-CN.md before moving between minor versions.

Editorial conclusion

Adopt PiDeck if you already run pi or DSH across several local repositories and want one window for session history, Git state and models.json editing. Do not adopt it if you need a stable, non-experimental tool: the README labels the project experimental, the current line is a 0.7.6-beta package version, and the latest release on the repository is v0.7.4 from 2026-09-08. Before installing, verify that a pi CLI is present on your PATH, because everything agent-related is delegated to it, and check the macOS update path, which opens the GitHub Release page instead of installing in place.

Frequently asked questions

Official sources

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