Pi Agent Desktop Electron

简体中文 · Build status · Release validation · AI correction log

A Windows Electron workbench that turns Pi Coding Agent from a CLI / Web runtime into an installable, persistent, and organized desktop workflow.

Pi Agent Desktop Electron is not an official Pi distribution and not a fork of Pi core. Pi provides the Coding Agent, Pi Web provides the Web interface and runtime, and this project adds desktop startup, windows, workspaces, long-running tasks, canvas collaboration, and Windows packaging.

Why This Product Exists

Pi's CLI is powerful for terminal users, but Windows users still need to install Node.js, remember commands, manage terminal windows, choose a workspace, handle session history, and keep a browser page visible during long tasks.

This project treats that gap as a product problem:

CLI / Web Agent → startup and windows → workspace and projects → background tasks → recoverable desktop delivery

The goal is not to reimplement model calls. It is to bring a local Agent into writing, research, automation, design, and product workflows while preserving Pi's local-first, extensible, user-controlled model.

Who It Is For

• Windows users who want Pi without living in a terminal.
• People who switch between multiple projects and need workspaces, sessions, and windows to stay organized.
• Users bringing a coding agent into writing, research, automation, scripting, and product-management workflows.
• People who need long tasks to continue after the main window is closed and remain recoverable from the desktop.
• Advanced users who want Pi's providers, models, sessions, skills, extensions, packages, and AGENTS.md in a repeatable workspace.

What I Built Beyond Pi Web

Original problem	Desktop product change	Result
Start-up requires a terminal and browser	Electron manages Pi Web runtime and desktop windows	Launch from a Windows desktop entry
Repeated launch creates duplicate windows	Single-instance lock and focus existing window	One application instance
Closing the window can interrupt work	Close-to-tray	Runtime continues in the background
Users must keep the main window visible	Progress Island	Verifiable status remains visible on the desktop
Sessions and project files are scattered	Project / task tree and file explorer	Organize sessions, templates, and outputs by workspace
References and annotations are separate	Cowart canvas window	Open, annotate, select, and send context beside Pi
New users lack durable workspace rules	PARA-style workspace template	Consistent Inbox, Projects, Templates, Archive, and Canvas
latest creates behavioral drift	Electron / runtime pinning	Reproducible builds and releases
Off-screen windows look lost	Window-bound recovery	Restore to a visible display area

How the Features Work

1. Windows Desktop Entry and Application Icon

The package provides a Windows shortcut, Start Menu entry, and PiAgent Desktop.exe. The installer, portable build, and runtime share the same Pi Agent product identity and icon.

2. Electron Desktop Workbench

Electron owns window lifecycle, single-instance behavior, Pi Web startup, recovery, tray integration, and the local runtime. Pi Web remains bound to 127.0.0.1; models, authentication, sessions, providers, and extensions continue to follow upstream Pi.

3. Project and Task Tree

The desktop shell adds a project / task tree to the Pi Web sidebar. Projects can be created, renamed, archived, and restored; sessions can be assigned to projects and kept as durable task units rather than disposable chats.

4. File Explorer and Workspace Order

The file explorer maps to the workspace template: 00_Inbox, 01_Projects, 02_Shared_Assets, 80_Templates, 90_Archive, and canvas. Research, plans, source files, and outputs stay next to the Agent workflow instead of being scattered across the desktop.

The repository includes workspace-template/:

• AGENTS.md: workspace-level Agent rules.
• WORKSPACE_GUIDE.md: daily workflow and project paths.
• FILE_ORGANIZATION.md: research, drafts, outputs, and archive rules.
• NAMING_GUIDE.md: project, file, and session naming.
• AGENT_USAGE_GUIDE.md: Agent usage and acceptance steps.

5. Taskbar and Progress Island

Progress Island is a small always-on-top task status window. It does not invent a completion percentage that cannot be predicted. It reports observable states such as idle, queued, thinking, executing, processing, wrapping up, and done.

The island polls the local /api/sessions endpoint and combines runningSessionIds with session-log inspection. It remains visible when the main window is hidden and can reopen the corresponding session.

When expanded, it shows recent tasks, state indicators, and the action to reopen a session. Completed work can be dismissed instead of being presented as active.

6. Background Task Execution

The main window close button means “hide and keep working”, not “terminate every process”. Pi Web, Cowart, and active tasks continue to run; the user can return through the task island, tray, or desktop entry. Only the tray command Exit (clean up all processes) performs a full shutdown.

7. Cowart Canvas

Cowart is a visual workspace based on tldraw. It opens as a companion window beside the Agent for references, notes, selections, and visual decisions. A selection can be sent back to Pi as @canvas selection, or the canvas can start a follow-up task through the trusted preload bridge.

8. Voice Input and Local Permissions

Voice input prefers Windows native dictation and provides local System.Speech or browser recognition fallbacks. Read-aloud was not added to the core direction because Windows already covers the primary need, while another model-backed speech service would add cost and privacy surface.

Relationship to Official Pi

Pi Coding Agent → Pi Web runtime → Pi Agent Desktop Electron → Windows package

Official Pi	Desktop Electron
Terminal interface	Independent Windows Electron window
User starts pi manually	Desktop shell manages Pi Web runtime
Current terminal directory	Default workspace plus PIAGENT_WORKSPACE override
User manages terminal windows	Single instance, recovery, and tray
CLI session management	Project / task tree and desktop Web sessions
User prepares Node.js	Release target includes a pinned runtime

Model calls, authentication, session format, project context, and Pi extension mechanisms remain owned by Pi and upstream dependencies.

AI Corrections and Product Trade-offs

• An early installer omitted several desktop modules, which established that a successful build command is not release acceptance.
• The first Progress Island showed an unmeasurable percentage; it was removed in favor of observable states.
• latest dependency drift led to pinned Electron, Pi Web, and runtime versions.
• Read-aloud was cut because integration and token costs did not fit the lightweight desktop-shell position; voice input remains.

See docs/ai-correction-log.md for the complete record.

Install and Run

Download the Release

Pi Agent Desktop v0.1.0 provides:

• Pi-Agent-Desktop-Setup-0.1.0.exe: Windows installer.
• Pi-Agent-Desktop-0.1.0-windows-x64.zip: portable package.
• SHA256SUMS.txt: integrity checks.

Windows may show a SmartScreen warning because the installer is not code-signed.

Run from Source

Requirements: Windows 10 or newer and Node.js 22.19 or newer.

npm ci
npm run install-runtime
npm start

Set a workspace:

$env:PIAGENT_WORKSPACE = 'D:\Projects\MyWorkspace'
npm start

Build

npm run check
npm run dist:installer
npm run dist:dir

Run the public demo workspace:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-public-demo.ps1

The script uses C:\Temp\PiAgentPublicDemo, isolated ports, isolated user data, and a generated redacted project tree. It does not read personal Pi sessions.

Privacy and Product Boundaries

The source and release package exclude:

• .env, API keys, authentication, model settings, and sessions;
• user workspaces, projects, local paths, Electron user data, and caches;
• personal screenshots, temporary build files, and real recruitment or client data.

The desktop runtime binds to 127.0.0.1. Uninstalling the shell does not automatically delete a user's Pi configuration or sessions. Providers and model availability remain user-configured.

Current Status

• Electron Windows shell, single instance, tray, window recovery, and Progress Island are implemented.
• Project / task tree, file explorer, workspace template, and Cowart canvas are implemented.
• Windows x64 installer, portable ZIP, and SHA-256 assets are generated.
• The installer is not code-signed.
• Clean Windows user validation should still be completed before a broad production release.

Sources and License

• Pi: Coding Agent foundation.
• Pi Web: Web interface and runtime.
• tldraw: Cowart canvas SDK.

The desktop shell uses MIT License. Upstream projects and dependencies retain their own licenses. See LICENSE and THIRD_PARTY_NOTICES.md.