PiDeck: An Electron Workbench That Wraps pi and DSH Agent Sessions

The Problem PiDeck Targets: Session Sprawl Across Local Repositories

If you run a coding agent inside several repositories, the state that matters ends up scattered. Session transcripts live wherever the agent CLI writes them, model configuration lives in JSON files you edit by hand, and Git status lives in a terminal you keep switching back to. PiDeck's stated purpose is to put those pieces in one desktop window: the README describes it as an open source desktop workbench for managing pi Agent sessions across local project directories, with import of Codex and Claude local sessions for unified browsing and recovery. The intended user is a developer who already runs local AI coding assistants in more than one project and wants session history, Git status and pi configuration visible in a GUI. One boundary is explicit in the README: PiDeck is not a pi fork. It is described as a lightweight Electron shell that launches multiple pi --mode rpc processes, so agent behaviour and session file reads and writes remain pi's own. That framing matters, because it means the tool is a management layer and inherits pi's capabilities and pi's failure modes.

How PiDeck Works: An Electron Shell Over pi RPC Processes and DSH utilityProcess

The architecture visible in the README is process orchestration. PiDeck starts one pi process per session in RPC mode, and the desktop UI handles project management, session management, the conversation view, configuration management and tool orchestration on top. The README states the shell does not replicate or hijack agent behaviour. Projects are isolated from one another, and the README notes that a project with a running agent cannot be deleted, which implies the app tracks live process state per project. For the second backend, DSH (DeepSeek Harness), the integration takes a different shape: the DSH host runs embedded as an Electron utilityProcess, with no dsh web invocation, no listening port and no background HTTP server, and it starts lazily so it does not slow application launch. Both backends share one project, and session lists and headers carry pi or DSH badges to distinguish them. Session-level features differ by backend: DSH sessions support paginated history browsing, fork from an anchor point with the fork text returned to the input box, and /compact for context compression, and the README states the original session is restored after an app restart. DSH approval requests and questions are answered through the same desktop Ask dialog used by pi sessions. The README does not document the RPC protocol itself, so how much of the session state PiDeck caches versus reads from disk is not stated.

Running PiDeck From Source and the Configuration Files It Edits

The README lists a quick start section for running from source, but the supplied excerpt does not include its commands, so the exact install steps cannot be reproduced here. What the material does establish is the runtime shape: PiDeck spawns pi --mode rpc processes, so a working pi installation is a prerequisite, and the Electron version is pinned at 38 with React 19 per the README badges. The configuration surface is concrete. PiDeck provides a visual editor for three pi files: models.json, auth.json and settings.json. The editor combines provider cards, a model grid, type-aware key-value editing and a raw JSON view of the source file, and the README states that saving requires restarting the agent for changes to take effect. Provider cards have a one-click connection test, and the README calls out a specific bug class it addresses: model validation no longer treats a configuration fallback as a successful test. A separate setting covers the Git executable path, with detection, and proxy settings are split between the pi agent subprocess and the desktop app, so model fetching and connection tests can route through the desktop proxy. The README also notes compatibility with pi 0.84.3, where context window, maxTokens and thinking levels adapt to what the endpoint returns, and the model catalog can be refreshed manually.

Session Import, Export and the Limits of the Unified History

The session layer is where PiDeck makes its strongest claim and where the documentation is least specific. Import works through a project right-click menu that pulls in Codex and Claude local sessions, converting them into PiDeck history entries for browsing and recovery. The README does not describe how the conversion maps message roles, tool calls or attachments, and it does not state whether an imported session can be resumed by the original Codex or Claude CLI afterward. Treat that as an open question to test rather than a documented guarantee. Export is one-directional and simpler: sessions export to HTML. Native session management covers create, rename, duplicate, delete, restart, reload and close agent, reachable from the sidebar or a context menu. A scale ruler on the right edge of a session maps to timeline positions so long conversations can be jumped through, and a draggable content width slider defaults to unlimited width. The practical limitation is that a unified view is not a unified format. PiDeck presents pi, DSH, Codex and Claude history in one list, but the README only claims browsing and recovery for imported sessions, not round-trip fidelity.

Where PiDeck Is the Wrong Tool

PiDeck adds a desktop process model on top of CLIs that already work in a terminal, and that overhead is not free. The README labels the project experimental, and the current line is 0.7.5-beta, so anyone who needs a frozen, long-supported release should look elsewhere. The app is Electron-based, which means a Chromium runtime and its memory footprint sit alongside the agent processes you are already running; on a machine juggling several concurrent agents, that is a real cost the README does not quantify. The feature list is broad (desktop pet, Feishu bot integration, LAN web service, prompt and skill stores, image generation backend), and breadth in a pre-1.0 Electron app usually means each surface gets less hardening. Single-repository users get little from the multi-project isolation that is the core premise. And because PiDeck starts pi --mode rpc processes rather than embedding the agent, a pi installation problem, a version mismatch, or a proxy misconfiguration on the agent subprocess will surface as a PiDeck failure even though the fault is upstream. The README's own framing supports this reading: all agent capability comes from pi natively, and PiDeck does not replicate it.

Alternatives and the Actual Difference in Approach

The most direct alternative is the pi CLI itself. Running pi in a terminal per repository gives you the same agent, the same session files and the same models.json, auth.json and settings.json, with no Electron layer and no RPC process management. What you give up is everything PiDeck adds around it: the multi-project sidebar, the session browser with a timeline ruler, the Git panel with branch switching, the terminal dock, the visual config editor and the connection tests. If your work is one repository and one session at a time, that trade goes the other way. A second comparison is Codex and Claude's own local clients, which PiDeck imports from rather than replaces. Those tools keep their sessions in their own ecosystems; PiDeck's pitch is that you can browse them next to pi and DSH history in one list. The README does not claim PiDeck can write sessions back into Codex or Claude, so the import is a one-way consolidation, not a replacement client. A third option is a general terminal multiplexer plus an editor with a Git panel. That combination covers panes and version control but has no concept of an agent session, no import path and no model configuration UI, so it solves a different problem.

Maintenance, Updates and What the MIT Licence Leaves Open

PiDeck is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is a permissive baseline, but it says nothing about the project's operational dependencies, and this is where the maintenance picture gets more involved than the licence suggests. PiDeck tracks two external agent backends: pi and DSH. The README documents compatibility work for a specific pi version, 0.84.3, which implies that pi releases can change behaviour PiDeck depends on, and that upgrading pi may require a matching PiDeck update. DSH support is described as a deep integration with an embedded host, so it carries the same coupling risk. The update mechanism is platform-dependent: the README states updates are always checked in the background and autoDownloadUpdates defaults to on, Windows and Linux use a bundled updater, and macOS users install manually from GitHub Releases. Pi CLI checks run separately. For a team, that means two update channels to track and a macOS install step that cannot be automated through the app. The README also mentions a LAN web service that exposes a browser version over IP and port, plus a Feishu bot binding; if you enable either, you are widening the app's network surface, and the README excerpt does not include the security section that would describe the controls around them. Anyone running PiDeck in a corporate environment should read that section in full before turning those features on.

Editorial conclusion

Adopt PiDeck if you already run pi or DSH in more than one local repository and want session history, Git state and model configuration in a single window; skip it if you work in one project, prefer the terminal, or need a stable release, since the README labels the project experimental and the current line is 0.7.5-beta. Before committing, verify three things on your own machine: that pi is installed and reachable so PiDeck can spawn pi --mode rpc, that your existing pi session files are detected after you add a project directory, and that the Codex and Claude import path produces sessions you can actually resume. Also confirm how you will receive updates on your platform, because the README states Windows and Linux use a bundled updater while macOS installs must be downloaded from GitHub Releases manually.

Official sources

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