PI-Desktop README

The project's README from github.com/vastsa/PI-Desktop. As one markdown file: README.md.

PI-Desktop

PI-Desktop

A modular desktop workspace for AI agents

Bring projects, agents, models, plugins, and workflows into one persistent desktop environment.

Local-first · Model-agnostic · Plugin-powered · macOS / Windows / Linux


Release Downloads Stars CI License Reddit


Download · Documentation · Build a Plugin · Screenshots · 简体中文


PI-Desktop

Your projects stay local · Your models stay replaceable · Your workspace stays yours

Current release line: 0.15.x (Early Preview).

Why PI-Desktop?

Terminal agents are great at execution. IDE agents are great at living inside an editor.

PI-Desktop goes one step further:

Give AI agents a persistent, independent, and extensible desktop workspace of their own.

Independent Workspace

No dependency on a specific IDE or terminal.

Projects, sessions, reviews, previews, and agents all live in their own workspace.

Plugin-Powered

Plugins extend more than the agent.

Add panels, views, widgets, tools, MCP servers, themes, and background services.

Agent Orchestration

One agent is not always enough.

Delegate to Subagents or coordinate full Worker Sessions in parallel.

Model Freedom

Cloud models, local models, custom gateways, compatible APIs.

Switch models without rebuilding your workflow.

It is not a wrapper around one model. It is not another IDE extension.

It is a desktop platform for agent workflows.

Plugins are part of the workspace, not an afterthought

PI-Desktop keeps the Core focused.

Your actual workflow is assembled through extensions.

Agent

Extend what the agent can do

Agent Tools Skills Completion pi Extensions

Workspace

Extend the desktop itself

Commands Panels Work Panel Views Floating Widgets Themes

Platform

Extend the runtime

MCP Servers Resident Services Plugin Message Bus

A plugin does not have to be “just another tool.”

It can be an entire product:

Voice Agent
├── Floating Widget
├── Speech Service
├── Agent Tool
└── Commands

GitHub Workspace
├── Work Panel
├── MCP Server
├── Agent Tools
└── Background Service

Session Analytics
├── Dashboard
├── Commands
└── Workspace View

What can a plugin add?

Capability What it enables
Command Add actions to the global command system
Panel Open a standalone plugin interface
Floating Widget Build voice orbs, status lights, timers, and other floating UI
Work Panel View Add new views to the right-side workspace
Agent Tool Register tools callable by the agent
Completion Use the models already configured by the user
Skill Add reusable agent capabilities and workflows
Theme Customize workspace appearance
MCP Server Connect local or remote MCP servers
Service Run persistent background work
Message Bus Let plugins communicate with each other

Plugins can be distributed as .piplug packages or installed through the marketplace.

Build your first plugin →

One foundation, many workflows

                         PI-Desktop
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
        Agent            Workspace           Platform
          │                  │                  │
     Agent Tools           Panels              MCP
       Skills             Widgets            Services
     Subagents             Views            Message Bus
   pi Extensions          Themes
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
                       Your Workflow

PI-Desktop can simply be your coding agent.

Or you can turn it into:

AI Development Workspace · Voice Agent · DevOps Console · GitHub Workspace · Data Assistant · Multi-Agent Control Center · Automation Platform

The Core provides the foundation. Plugins decide what your workspace becomes.

Three ways to work

Agent

Give it a task. Let it work.

Read code, edit files, run commands, test, and iterate.

Best for day-to-day development.

Plan

Review the approach before execution.

The agent studies the project first and produces an implementation plan.

Best for refactors and high-risk changes.

Goal

Define the outcome. Let the agent choose the path.

Lock the objective and acceptance criteria, then let the agent drive execution.

Best for complex and long-running tasks.

Privileged operations still pass through PI-Desktop's permission layer.

When one agent is not enough

Complex work should not be forced into one context window.

PI-Desktop provides two levels of delegation.

Subagents

Delegate independent work to background agents:

Code exploration · Implementation · Test analysis · Research · Review

Each Subagent gets its own context and reports the result back to the parent agent.

Session Orchestrator

For longer-lived work, delegate to full Worker Sessions.

Main Session
│
├── Worker A
│   └── Frontend
│
├── Worker B
│   └── Backend
│
├── Worker C
│   └── Tests
│
└── Worker D
    └── Review

Workers are full PI-Desktop sessions:

Independent context · Independent execution · Directly inspectable · Reusable · Full transcript

Session Orchestrator

Coordinate multiple Worker Sessions from one parent Session

 Worker Session

Each Worker remains a full, inspectable Session

Move from “one agent helps me code” to “multiple agents divide and complete the work.”

Built for work that lasts

PI-Desktop is organized around:

Project → Session → Agent → Work

—not around disposable chat threads.

You can:

A Session can continue across multiple app launches.

See what the agent is doing

PI-Desktop Session

Persistent Sessions instead of disposable chats

 PI-Desktop Model

Switch models and reasoning levels inside the Session
PI-Desktop Plugins

A plugin marketplace that extends both the agent and the desktop

 PI-Desktop Providers

Connect your own provider, gateway, or local model

Explore more screenshots →

Swap the model, keep the workflow

PI-Desktop does not tie your workflow to a single model vendor.

Use:

OpenAI · Anthropic · OpenAI-Compatible APIs · Custom Gateways · Ollama · LM Studio · Local Models

Configure each model independently:

Provider · Model ID · Context Window · Output Limit · Reasoning / Thinking · Temperature · OAuth · API Key · Endpoint

Different Sessions can use different models.

The same Session can switch models at any time.

Planning     → Model A
Coding       → Model B
Review       → Model C
Private Task → Local Model

The model is a replaceable component of the workflow — not the workflow itself.

Already using another coding agent?

Keep your existing work.

PI-Desktop can import local sessions from:

Claude Code · Codex · OpenCode · Pi

Local-first

PI-Desktop does not require you to move your development environment into our cloud.

Data Default behavior
Projects Local
Sessions Local
Settings Local
Logs Local
API credentials OS Keychain
PI-Desktop telemetry None
Model requests Sent directly to your configured provider

No mandatory PI-Desktop account.

No mandatory PI-Desktop relay.

When using a remote model, the context required for the request is sent directly to that provider.

You control the permissions

Agents can read files, edit code, run commands, call tools, use extensions, and delegate work.

Privileged operations still pass through the permission layer:

Agent
  ↓
Tool Request
  ↓
Permission Layer
  ↓
Allow / Ask / Deny
  ↓
Execution

You decide how much autonomy each Session gets.

Get started

01

Download

Install PI-Desktop

02

Connect a model

Configure a Provider

03

Open a project

Choose a local repository

04

Start working

Agent / Plan / Goal

Download PI-Desktop →

macOS · Windows · Linux

Packages

Platform Architecture Package
macOS Apple Silicon .dmg / .zip
macOS Intel .dmg / .zip
Windows x64 Installer / .zip
Linux x64 .AppImage / .deb / .rpm / .asar

macOS releases are signed with a Developer ID certificate and notarized by Apple.

Linux Compatibility

Linux x64 packages require glibc 2.35+.

Common supported distributions include:

  • Ubuntu 22.04+
  • Debian 12+
  • Fedora 36+

Check your current version with:

ldd --version

Built on Pi

PI-Desktop is built on the pi ecosystem.

The Agent Runtime uses:

Pi provides the Agent Engine. PI-Desktop builds the persistent desktop workspace, sessions, permissions, plugins, and agent orchestration around it.

For Developers

PI-Desktop can also serve as a host platform for building agent products.

You can build:

Plugins · MCP Servers · Skills · Agent Tools · pi Extensions · Themes · Panels · Floating Widgets · Background Services

Plugin quick start

Built-in templates include:

Plugins can be created and loaded directly as Development Plugins.

Plugin Development Guide →

Run from source

Development Setup

Requirements

  • Node.js >=22.19
  • pnpm >=10
  • Stable Rust Toolchain

Start

git clone https://github.com/vastsa/PI-Desktop.git
cd PI-Desktop

pnpm install

cargo build -p host-core
pnpm build:js

pnpm dev

Validate

pnpm typecheck
pnpm lint
pnpm test

Documentation

Documentation · Architecture · Specification · Plugin Development · E2E Test Plan · Release Runbook · AGENTS.md

Contributing

Contributions are welcome:

Issues · Pull Requests · Plugins · Skills · MCP Integrations · Documentation · Translations

For standalone capabilities, consider one question first:

Would this be better as a Plugin?

Keep the Core focused. Let the ecosystem grow.

Report an Issue · Open Issues · Build a Plugin

Project Trend

PI-Desktop on Trendshift

Friends

Linux.Do — A new ideal community

Model Acknowledgements

Not by a lone genius, but by a token-powered construction crew.

PI-Desktop has been built with the help of models from multiple providers.

More than 27 billion tokens have been used across development, refactoring, review, design, and debugging.

Thanks to every human contributor — and every model that helped us build it.

License

PI-Desktop is licensed under the GNU Lesser General Public License v3.0.

See LICENSE for details.

PI-Desktop

PI-Desktop

Build your own Agent workspace.

Your models · Your agents · Your plugins · Your workspace


Download · Documentation · Build a Plugin



Local-first · Model-agnostic · Plugin-powered

PI-Desktop (vastsa/PI-Desktop)

Searching Database…

6.9K ·GitHub
PI-Desktop
What is this?PI-Desktop is a local-first desktop workspace for AI coding agents, built with Electron and a Rust host core on top of the pi Agent Harness, where projects, models, sessions and plugins all live together instead of in disposable chat windows.
Is this just a chat wrapper around one AI model or an IDE plugin?Neither — it is a standalone desktop platform for agent workflows, not tied to a single model and not living inside an editor; the whole workspace (panels, tools, MCP servers, themes) is extended through plugins.
How do I install and start using it?Download the prebuilt app for macOS, Windows, or Linux, connect a model provider, and open a local project to start an Agent/Plan/Goal session. Building from source instead requires Node.js, pnpm, and a Rust toolchain.
Do I need an Anthropic or OpenAI API key, or can I run local models?Neither is mandatory: you can plug in OpenAI, Anthropic, OpenAI-compatible APIs, custom gateways, Ollama, LM Studio, or fully local models, and each session can use a different one.
Any install pitfalls or maturity concerns before trying it?It's still an Early Preview (0.15.x release line), so expect rough edges; Linux builds also require glibc 2.35+ (Ubuntu 22.04+, Debian 12+, or Fedora 36+).
Where does my code and data go?Projects, sessions, settings and logs stay local by default, API credentials go into the OS keychain, there's no mandatory PI-Desktop account or telemetry, and model requests are sent directly to whichever provider you configured.
What's the difference between a Subagent and a Worker Session?Subagents handle quick background tasks like code exploration or review and report results back to the parent agent, while Worker Sessions are full, independent PI-Desktop sessions with their own inspectable context that can be coordinated together for longer-running work.
Can I bring over sessions from the coding agent I already use?Yes, PI-Desktop can import local sessions from Claude Code, Codex, OpenCode, and Pi so you don't lose existing work.
What can a plugin actually add to the workspace?Plugins can add commands, panels, floating widgets, work-panel views, agent tools, completions, skills, themes, MCP servers, and background services, and can even ship as full products via .piplug packages or the marketplace.
What are the Agent, Plan, and Goal modes?Agent mode lets the AI act directly on a task, Plan mode has it draft an implementation plan for your review before executing, and Goal mode lets it choose its own path to a defined outcome and acceptance criteria.
What are similar projects?pi-harness, codex-host, ruflo, Kun, evenfire, 1code, CodePilot, holaOS
Which topics is it in?pi-agent, pi, lgpl, plugins, autonomous-agents, i18n, model-context-protocol, agent-orchestration, ollama, electron, multi-agent, local-first
Creator
vastsa
Size
153.1 MB
Stars
6.9K
Updated
CommitOct 16Releasev0.20.1Oct 13
Age
3y
Commits · 90 Days