PI-Desktop review Session files and storage migration
Eleven local checks examine PI-Desktop file migration, lock exclusions, symlink handling and failure behavior without claiming a complete Electron or Rust migration.
AgentIndex · Published 2026-11-05 · Updated 2026-11-05
PI-Desktop puts coding-agent projects, persistent sessions, models and plugins into an independent desktop workspace. Its selection value is continuity: a project should remain understandable after an app restart, a change of model or a move to another storage directory. A feature list alone cannot establish that continuity.
We tested a narrow but consequential part: copying profile and session files to a new location. The selected implementation retained originals, excluded installation locks at the browser root, rewrote selected symlink destinations and rejected source changes during verification. Those are useful properties for a local workspace. Database relocation and successful application restart remain separate acceptance steps.
Version and test boundary
This review pins commit 836ccd084147bedf916e56c859c1529ae63d2ac6 on November 5, 2026. The root package reports 0.21.0, and the README calls the 0.21.x release line Early Preview. The architecture combines Electron, a Rust host core and the pi agent harness. The repository license is LGPL-3.0. Project description
Eleven named checks ran with Node.js 26.6.0 on macOS arm64. They loaded the real storage and preference modules using temporary synthetic profiles. Electron's original-fs import was mapped to Node's physical filesystem API. We supplied a recording or deliberately failing relocation callback instead of starting the Rust host. The fixture and source fingerprints document this boundary.
No Electron window, production profile, SQLite migration or model session was opened. Windows junction behavior, packaged .asar handling and interrupted-process recovery were not exercised. A complete source build requires Node, pnpm and Rust; this selected-module test does not replace it.
| Scenario | Observed behavior |
|---|---|
| Destination inside source | Rejected before creating it |
| Unrelated nonempty destination | Rejected; existing file preserved |
| Symlink destination or overlapping path through symlink parent | Rejected |
| Synthetic session copy | New contents matched; original remained |
| Browser-root installation locks | Omitted from copied browser root |
| User lockfiles in data and browser subdirectory | Preserved |
| Internal absolute and external relative symlinks | Selected targets retained through remapping |
| Source changed at verification boundary | Migration rejected |
| Injected relocation failure | Error propagated; original session retained |
| Malformed preference file | Rejected rather than silently replaced |
Separate storage roots before copying
The destination validator canonicalizes paths and compares the destination with the data root, browser root and installation anchor. Our nested target was rejected without being created. A path beneath a symlink pointing into source storage was also rejected. This matters because a superficially different pathname can still refer to the same data tree. Target validation and migration
An occupied directory containing an unrelated file was refused without deleting that file. For a first-install case with no data root, the selected routine created the new data directory and did not invoke the relocation callback. These are useful edge cases, but permission changes, network volumes and real destination capacity failures were not part of our tests.
The source implementation describes migration as a cold copy: database, browser, plugin and log writers must be stopped. That requirement determines when the operation belongs in the product lifecycle. Copying a running profile and hoping that verification passes is not a substitute for coordinating those writers.
File verification and the relocation boundary
The synthetic session JSONL file was copied byte-for-byte, while its original remained readable. Progress reached complete and the supplied callback received the old and new data roots. The implementation computes hashes while copying and verifies source and destination before calling relocation.
We then changed a source session at the start of verification. The routine rejected the migration. In another test, an injected callback failure propagated while the original session remained intact. This establishes behavior at selected failure boundaries, not a complete recovery transaction. Partial destination files may remain, and our fixture did not test reopening the app after a crash.
Most importantly, the recording callback does not rewrite database paths. A successful file-copy result cannot prove that the Rust host opens relocated databases, resumes a session or finds every attachment. Before deleting old storage, a real adoption trial should reopen the application, inspect representative sessions and attachments, and confirm that the intended root is active.
Locks and links are part of the profile contract
Browser-root lockfile and SingletonLock were omitted. A user-owned lockfile in the data root and another under a browser subdirectory were retained. This scoped exclusion is preferable to assuming that every file named lockfile is disposable; projects and user material can legitimately contain one.
An absolute symlink to a session within the source tree was rewritten to the new session path. A relative link to an external fixture continued resolving to the same external file. The external content was not copied into the new root. Thus moving a profile does not necessarily produce a self-contained archive. This matters for backup and portability: linked material can still depend on another location.
The tests ran on macOS. They do not establish Windows junction semantics, network share support or the behavior of a packaged Electron filesystem. Those should be evaluated on the deployment platform rather than inferred from a passing Node test.
Preferences preserve explicit state
A missing preference file produced default roots and an empty backup list. A valid preference containing new roots, old backup roots and a pending migration round-tripped through the real writer and reader. Invalid JSON and relative roots were refused. Preference implementation
Refusing malformed state makes a problem visible instead of quietly starting with different roots. It also means an operator needs a recoverable preference file and a clear way to identify the last working storage location. Our normal write/read test does not establish atomic behavior under power loss or a failing filesystem.
Adoption decision
PI-Desktop is worth a trial if you want a desktop workspace across projects and replaceable model providers, and can accept an Early Preview release. Its plugin system extends tools, panels and services, so plugin compatibility and access deserve their own evaluation. Local-first describes where workspace state lives; using a cloud model still sends requests to that provider.
Start with a disposable project and test persistence, attachments and a complete move-and-restart sequence on the target operating system. The evidence here supports the selected file layer, without ranking model quality or proving plugin isolation. For an Android-oriented DSH client, see the dsh-Go sharing review. For filesystem-based handoffs between agent sessions, see the Crew memory review.