How to Contribute to PI Desktop: A Complete Developer's Guide

To contribute to PI Desktop, fork the vastsa/PI-Desktop repository, install Node ≥22 with pnpm and a stable Rust toolchain, create an isolated feature branch per AGENTS.md guidelines, and submit a pull request after passing type-checking, linting, and tests.

PI Desktop is a local-first, multi-layered desktop workspace for AI coding agents. Before submitting changes to the vastsa/PI-Desktop repository, it is essential to understand how the four architectural layers interact and the specific workflow enforced by the maintainers.

Understanding the PI Desktop Architecture

PI Desktop separates concerns across four distinct layers defined in docs/spec/02-architecture/01-architecture.md. Contributors should identify which layer aligns with their expertise before making changes.

The Renderer Layer (React UI)

The Renderer is a React-based UI that hosts chat interfaces, project panels, settings, plugins, and the command palette. It runs without Node integration, making it ideal for contributors focused on front-end improvements, i18n strings, or user experience enhancements.

The Electron Main Layer

The Electron Main process acts as a thin orchestrator handling window lifecycle, IPC routing, and optional MCP loop-back control. Modifications here require understanding Electron's main process architecture and the IPC glue code located in apps/desktop/src/.

The Rust Host Core

The Rust Host Core is the privileged backend that owns filesystem access, SQLite persistence, secret storage, and plugin host services. Located at the workspace root with Cargo.toml defining the dependencies, this layer requires Rust expertise for extending permission gates, file adapters, or security features.

The pi Agent Sidecar

The pi Agent Sidecar is a Node process that runs the pi-ai agent loop, streams model responses, and executes turn orchestration. This layer bridges the AI capabilities with the desktop environment.

Setting Up Your Development Environment

Before contributing to PI Desktop, ensure you have Node ≥22, pnpm, and a stable Rust toolchain installed. The repository uses a monorepo structure with both JavaScript/TypeScript and Rust codebases.

Clone the repository and install dependencies:

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

# Install Node dependencies (pnpm is required)

pnpm install

# Build the Rust host core

cargo build -p host-core

# Build the JavaScript/TypeScript parts

pnpm build:js

# Run the desktop app in development mode

pnpm dev

These commands initialize the Renderer, Electron Main, Rust Host Core, and Agent Sidecar for local development.

The Contribution Workflow

The vastsa/PI-Desktop repository enforces an isolated development workflow documented in AGENTS.md. Follow these steps to ensure your contribution meets the project standards:

1. Open an issue to discuss bug reports, feature requests, or documentation improvements, allowing maintainers to align your work with the project roadmap.

2. Fork the repository and create a dedicated branch. Each contribution must live in its own branch and worktree, following the isolated development principles specified in the project's guidelines.

3. Set up the development environment as described above, verifying that cargo build -p host-core completes successfully and pnpm dev launches the application.

4. Make incremental, test-driven changes. Every logical change must be committed separately, and the CI pipeline expects type-checking, linting, and unit/E2E tests to pass before merging.

5. Update documentation and specs where appropriate. Architectural changes require adding an Architecture Decision Record (ADR) in the docs directory, while features need updates to the E2E test plan.

6. Submit a pull request. Maintainers review the principle of your change, run the CI pipeline, and merge the PR once it satisfies the repository's baseline and specifications.

Testing and Validation

Before submitting your contribution, run the validation commands listed in the README to ensure code quality:

# Verify TypeScript typings

pnpm typecheck

# Lint the codebase

pnpm lint

# Run unit and integration tests

pnpm test

All three commands must pass to satisfy the CI pipeline requirements. The project enforces these checks to maintain stability across the React, Electron, and Rust layers.

Contributing Plugins and Extensions

You can extend PI Desktop without modifying the core application by creating plugins, Skills, MCP servers, or Subagents. These components live in the plugins/ directory and follow a manifest-based architecture.

Create a new Skill by adding a manifest.json file:

{
  "name": "My Sample Skill",
  "contributes": {
    "skills": [
      {
        "id": "sample-skill",
        "description": "Demonstrates adding a custom skill",
        "instructions": "When invoked, echo back the user's input."
      }
    ]
  }
}

Install the plugin locally for testing:

pnpm plugin:install ./plugins/my-skill

The plugin appears in Plugins → Marketplace and can be activated per project. Refer to docs/plugin-development.md for the complete plugin publishing workflow.

Key Files for Contributors

Understanding these core files helps you navigate the codebase effectively:

• README.md — High-level project overview, getting-started guide, and contribution basics.
• AGENTS.md — Mandatory rules for AI agents, isolated development workflow, and commit policy.
• package.json — Defines the npm workspace, scripts, and top-level dependencies for the JavaScript side.
• Cargo.toml — Rust workspace manifest that builds the host-core binary and defines crate dependencies.
• docs/spec/02-architecture/01-architecture.md — Formal architecture specification with the layered diagram.
• apps/desktop/src/ — Source for the Electron renderer, UI components, and IPC glue code.
• plugins/ — Location for community-built plugins, Skills, MCP servers, and Subagents.
• docs/plugin-development.md — Step-by-step guide for creating and publishing plugins.

Summary

• PI Desktop uses a four-layer architecture: React Renderer, Electron Main, Rust Host Core, and pi Agent Sidecar.
• Contributors need Node ≥22, pnpm, and Rust to build the project locally.
• The workflow requires opening issues, using isolated branches, and following AGENTS.md guidelines.
• All submissions must pass pnpm typecheck, pnpm lint, and pnpm test before CI approval.
• Plugins extend functionality without core modifications using manifest.json files in the plugins/ directory.

Frequently Asked Questions

What are the system requirements for contributing to PI Desktop?

You need Node.js version 22 or higher, pnpm for package management, and a stable Rust toolchain for compiling the host core. The build process requires running cargo build -p host-core for the Rust backend and pnpm build:js for the TypeScript components.

How do I submit a new plugin to PI Desktop?

Create a new folder in plugins/ containing a manifest.json file that defines your Skill, MCP server, or Subagent contributions. Test it locally using pnpm plugin:install ./plugins/your-plugin, then submit a pull request following the isolated development workflow described in AGENTS.md.

What testing is required before submitting a pull request?

You must run pnpm typecheck to verify TypeScript typings, pnpm lint to ensure code style compliance, and pnpm test to execute unit and integration tests. The CI pipeline enforces all three checks before merging any contribution to the main branch.

Where is the architecture documentation located for PI Desktop?

The formal architecture specification is located at docs/spec/02-architecture/01-architecture.md, which includes diagrams and detailed descriptions of the Renderer, Electron Main, Rust Host Core, and pi Agent Sidecar layers. This document defines how the four components interact and where specific features should be implemented.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}