Pi Agent Desktop User Guide

Follow these steps to install the app, configure a model, and start your first conversation.

1Install the appChoose the package for your system 2Configure a modelSign in or enter an API key 3Choose a projectCreate your first session 4Add extensionsInstall Skills, Plugins, or channels

Download and install

Open the download page. The site highlights the package that matches your system. Desktop packages include the Pi Coding Agent runtime, so normal use does not require a separate Pi CLI installation.

macOS

Choose arm64 for Apple Silicon (M-series) or x64 for an Intel Mac. Open the DMG and drag the app to Applications.

Windows

Windows 10 and 11 x64 are supported. Run the EXE installer and follow the setup wizard.

Linux

Linux x64 is available as an AppImage. Make it executable, then open it from your file manager or application menu.

Install on macOS

Download the Apple Silicon or Intel DMG for your Mac.
Open the DMG and drag Pi Agent Desktop to the Applications folder.
Open it from Applications. Production builds are signed and notarized by Apple.

Install on Windows

Download and run the Windows x64 installer.
Follow the setup wizard.
The installer is not code-signed yet. If SmartScreen shows “Unknown publisher,” confirm the file came from GitHub Releases, then choose More info → Run anyway.

Install on Linux

Download the Linux x64 AppImage.
Allow the file to run as a program in its properties, or run chmod +x Pi-Agent-Desktop-*.AppImage.
Open the AppImage. Linux updates are currently manual.

First launch: Choose a project folder, then open Settings → Models and configure a model. You can start even if you have never used Pi CLI.

Meet the main workspace

Messaging connected · 3 conversations 297K Token

Stack:Native HTML, CSS, and JavaScript
Format:Responsive single-page site with no dependencies
Entry:index.html

Open index.html directly in a browser to run it.

11,044 in · 147 out · $0.059606:33

Create a website that introduces DLYZZT/pi-desktop

06:35

Process details · 7 messages · 11 tool calls

GPT-5.6 Sol

The page is now a product site for DLYZZT/pi-desktop.

Highlights include:

Pi Agent Desktop positioning and download entry points
Sessions, tool calls, project files, models, and extensions
WeChat, Telegram, and Feishu / Lark messaging channels
Electron's three-process architecture and local privacy model
macOS, Windows, and Linux support
Links to GitHub, releases, and installation docs

Files:

index.html
assets/icon.png

1,028 in · 205 out · 48,640 cache · $0.035606:40

Message... Type / for commands or @ to reference filesSend

GPT-5.6 Sol High Standard Compact context

Explorer index.html

<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport"
content="width=device-width" />
<meta name="description"
content="Pi Agent Desktop" />
<title>Pi Agent Desktop</title>
<link rel="preconnect" />
<style>
:root {
--snow: #f6f9fb;
--white: #ffffff;
--ink: #102333;
--muted: #667783;
--line: #dce6eb;
--cyan: #08bce8;
--orange: #ff8b2c;
--green: #40d899;
}
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
body {
margin: 0;
color: var(--ink);
background: var(--snow);
}

The workspace contains sessions on the left, the conversation in the center, and files on the right.

Left: projects and sessions

Choose or switch the project folder
Create a new session
Search, switch, rename, or delete sessions
Open Settings at the bottom

Center: conversation

Send prompts and read streaming replies
Inspect reasoning and tool-call results
Choose the model, reasoning level, and tool preset
Add images or reference files with @

Right: files and previews

Browse files in the current project
Open several files in tabs
Preview code, Markdown, diagrams, and documents
Drag dividers to resize panels

Start your first session

Choose a project folder in the left sidebar.
Select New session.
Make sure an available model is selected below the composer.
Describe a goal, such as “Explain this project” or “Find the login page.”

For chat or temporary work, you can choose an empty folder. The Agent can read or modify project files only when you authorize the relevant tools.

Configure models

OpenSettings→Models

Pi Agent Desktop does not include model credits. Connect an existing model provider account or enter an API key from your provider.

Use an API key

Open Settings → Models and select Add provider.
Choose your model provider.
Paste the API key and save.
Select a model. If a Test action is available, use it to verify the connection.
Close Settings and choose the model below the conversation composer.

Use OAuth

Choose a provider that supports OAuth.
Select Sign in and complete authorization in your browser.
Return to the app and confirm the provider shows as connected.

Use a compatible custom service

For self-hosted services compatible with the OpenAI, Anthropic, or Google API, add a custom provider and enter its Base URL, API type, API key, and model information. Use this only when a standard provider does not meet your needs.

Connection failed? Check that the API key is complete, your account has credits, and your network can reach the provider. Then use the model card's Test action to see the provider error.

Skills settings

OpenChoose a project→Settings→Skills

This section focuses on settings. Each Skill's own documentation explains its capabilities and usage.

global~/.agents/skills/agents-sdk

Name

agents-sdk

SKILL.mdSkill instructions and usage rules

Agents SDK Build AI agents on Cloudflare Workers using the Agents SDK. Use this skill for stateful agents, durable workflows, real-time WebSocket connections, and scheduled tasks.

Save changes

Description When enabled, this Skill is available to the model for relevant tasks. Global Skills work in every project.

Choose a project, then open Settings → Skills.
Select an installed Skill and use the switch to control whether it is visible to the model.
To add one, select Add skill, search by name, choose Global or Current project, and install.
Edit the content only when you need custom instructions, then save your changes.

Tip: Use Global for reusable Skills and Current project for repository-specific Skills.

Plugins settings

OpenChoose a project→Settings→Plugins

The Plugins page lets you configure a source, installation scope, and enabled state.

Add PluginInstall from npm, a Git repository, or a local directory

Plugin source

npm:@scope/package

Install

npm:@scope/pi-plugin git:https://github.com/user/repo /absolute/path/to/plugin

Installation scope

globalproject

Install location~/.pi/agent/{npm,git}

Plugins can execute code. Install only from sources you trust.

Choose a project, then open Settings → Plugins.
Select Add plugin and enter an npm package, Git repository, or absolute local path.
Choose Global or Current project, then install.
Enable, disable, update, or remove Plugins from the installed list.
After changing Plugin settings, reload the current session.

Important: Plugins can execute code. Install only from sources you trust.

Messaging channel settings

OpenSettings→Messaging channels

Choose a channel and enter only the account information that channel requires:

Messaging channelsConnect accounts, control access, and bind conversations to Pi sessions.

Connect Feishu / LarkConnect TelegramConnect WeChat

Pi Telegram BotTelegram · @pi_desktop_bot

Running

Account name

Pi Telegram Bot

Default tools

Standard

Default project directory

~/Documents/pi-workspaceChoose…

Private chat access

Pairing required

Group access

Allowlist only

Bot TokenProtected by secure system storage

New BotFather token

Update token

SaveStopTest connection

Channel	Configuration
WeChat	Select Connect WeChat, then scan the QR code and confirm on your phone.
Telegram	Enter the Bot Token created with BotFather.
Feishu / Lark	Choose the platform and enter the App ID and App Secret for a custom enterprise app.

Save the account and configure its default project directory and access policy as needed.
Start the account and confirm its status is Running.
Use Test connection. Bind a messaging conversation only when it should share context with the current desktop session.

Developer tools settings

OpenSettings→Developer Tools

The app scans required tools automatically. Most users only need to act on items marked Missing or Unavailable.

Pi managed~/Library/Application Support/Pi Desktop/tools/node

Available

Node.jsJavaScript runtime for Skills, Plugins, Agent commands, and project operations.

Tool resolution

StatusAvailableSourcePi managedVersionv22.19.0Detected candidates2

Preferred source

Auto (recommended)

Choose…

Managed runtime

Node.js LTS + npmOfficial source · Installed

v22.19.0Repair

Managed tools stay in Pi Desktop's private directory and do not modify the system PATH.

Select Rescan to see each tool's status, source, and version.
Leave installed tools on Auto. If detection is wrong, use Choose to select a path.
When a managed version is available for a missing tool, select Install. Use Repair if managed files are damaged.

You do not need everything: Leave healthy tools alone. Managed tools stay in Pi Desktop's private directory and do not change the system PATH.

Updates, background operation, and local data

Check for updates

Open Settings → About to check for stable releases. macOS and Windows can download and install updates in the app. Linux AppImage users currently download new versions manually.

Keep messaging channels online

Enable Minimize to tray when closing in Settings → General. Closing the main window then keeps channels running; choosing Quit from the tray fully stops the app.

Local data

Sessions and Pi configuration are stored locally in ~/.pi/agent/ by default.
Existing Pi CLI users can reuse their current sessions and configuration.
Model requests still go to your selected model provider, so review that provider's privacy policy.
Messaging credentials are encrypted with the operating system's secure storage and are never displayed again in Settings.

Frequently asked questions

Do I need to install Node.js or Pi CLI?

No. Desktop packages include the Pi Coding Agent runtime. Check Settings → Developer Tools only when a Skill, Plugin, or Agent command requires an additional tool.

Why do Skills and Plugins ask me to choose a project first?

Skills and Plugins can be installed per project, so the app needs the current project folder. Choose one in the main sidebar, then reopen Settings.

Why can’t I send a message after configuring a model?

Confirm a model is selected below the composer, then check the API key, account credits, and network connection. Use Test on the provider card to see the exact error.

Why is there no reply after approving channel pairing?

The first message triggers pairing and is not sent to the Agent. After approval, ask the same user to send a new message.

Why does a messaging channel go offline when I close the window?

Enable Minimize to tray when closing in Settings → General. Choosing Quit from the tray or application menu stops all channels.

What should I do when Windows SmartScreen appears?

The Windows installer is not code-signed yet. Confirm it came from GitHub Releases, then select More info → Run anyway.

Is Linux supported?

Yes, on Linux x64 through AppImage. Linux ARM64 builds are not available yet, and AppImage updates are currently manual.

How do I report a problem?

Record the app version, operating system, and error message, then open a GitHub Issue. Never include API keys, tokens, app secrets, or other credentials.