Pi Agent Desktop User Guide

Download and install

Open the download page. The site highlights the package that matches your system. The v0.2.0 desktop packages include Pi Coding Agent 0.84.0, and macOS and Linux also bundle Herdr v0.8.2. Normal use does not require a separate Pi CLI installation.

Install on macOS

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

Install on Windows

1. Download and run the unsigned Windows x64 Beta installer.
2. Follow the setup wizard.
3. 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

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

Meet the main workspace

Start your first session

1. Choose a project folder in the left sidebar.
2. Select New session.
3. Make sure an available model is selected below the composer.
4. 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.

Auto-titles and returning to the latest message

After the first meaningful message in a new session, the app uses the current model in the background to generate a title of up to 40 characters and updates the sidebar in real time. The request never enters session history or blocks the normal reply; if the model is unavailable, the beginning of the message provides a local fallback.

• Turn Auto-title new sessions off or on under Settings → General → Conversation.
• Manual names always win and are never overwritten by an automatic title.
• Slash commands, blank text, single-character messages, and image-only messages do not trigger a title.
• After scrolling upward, use the floating Scroll to bottom button to return to the latest content and re-enable automatic following during streaming.

Adjust chat size and conversation width

OpenSettings→General→Conversation

• Choose Small, Standard, Large, or Extra Large chat text. Changes apply immediately and persist across restarts.
• Comfortable width stays at 760px; Expanded adapts to the window up to 960px.
• Messages, process details, and the composer share aligned content boundaries in both wide and minimum-width windows.

Send attachments and use local file links

• Add images or any file through drag and drop, paste, or the attachment button beside the composer. Non-image attachments appear as file cards.
• Attachments can be sent without text. Messages with attachments can also enter the Steer / Follow-up queue while the Agent is streaming.
• If sending fails, attachments and text merge back into the current draft without overwriting anything typed while the send was in progress.
• Markdown messages recognize Windows, POSIX, and UNC local paths. Repository-relative paths open inside the app, while absolute paths can be revealed in the system file manager.
• Right-click a local file link to open it, choose the default app or Open with, save a copy, copy its path or text contents, or reveal it in its folder.
• When you type @ to reference a project file, the app browses and searches on demand with up to 300 candidates. In a user-home workspace, AppData or Library is hidden by default but remains accessible when explicitly typed.
• If the file-search tool is unavailable, times out, or fails, the UI shows a fallback state and keeps current-directory candidates instead of blocking input or silently returning incomplete results.

Use the built-in browser

OpenRight side of the workspace→Browser

The built-in browser hosts real Chromium pages. You and the Agent operate the same page, with tabs, profiles, and login state preserved, and you can take over at any time.

Manage browser permissions

Open Settings → Browser to manage global defaults and persistent policies for individual sessions. Grants from the authorization dialog are temporary for the current session and can be revoked at any time.

Advanced browser mode

Advanced mode adds trusted input, network inspection, a JavaScript knowledge store, and confirmed write-request replay in a dedicated profile. The switch lasts only for the current app launch, and Agent tools never receive or return cookie values.

Use Herdr Agent fleets

OpenSettings→Herdr

v0.2.0 integrates Herdr v0.8.2 / protocol 20. Pi can use herdr_* tools to manage a local Agent fleet from the original conversation, while the title bar shows Fleet status and the right-side Herdr terminal supports observation, troubleshooting, and explicit takeover.

Prepare the Herdr runtime

1. On macOS or Linux, open Settings → Developer Tools and find Herdr. A digest-verified v0.8.2 runtime is bundled, so you can install, update, repair, or remove the private runtime without a separate network download.
2. Open Settings → Herdr, enable the integration, choose Attach or Managed mode, enter a Herdr Session name, and optionally enable automatic connection.
3. Attach connects to a system Herdr server that you start and stop yourself; Pi Desktop never stops it. Managed starts, monitors, and restarts Pi Desktop's private server within limits.
4. Managed stops its private server when Herdr is disabled, the mode changes, the runtime is removed, or the app exits. It never takes over or terminates an external Herdr.

Manage Agents from the conversation

• Twenty-four herdr_* tools cover Fleet queries, workspace / tab / pane creation and management, Agent launch and prompting, waits, key input, state explanation, process diagnostics, and output waits.
• Title-bar status is grouped by workspace, tab, pane, and Agent, showing idle, working, blocked, done, or unknown states on both the start screen and active sessions.
• Supported Agent CLIs include pi, claude, codex, gemini, omp, opencode, copilot, kimi, droid, grok, and qwen. Availability is checked before launch.
• Pi Sessions and Herdr Sessions are independent. Herdr prompts are not written to Pi session history or compaction summaries.

Observe and take over a terminal

• The right-side Herdr terminal supports ANSI output, auto-fit sizing, read-only observation, explicit keyboard takeover, input throttling, reconnection, and bounded buffering.
• Closing the terminal view does not close the Herdr pane or Agent. You can choose whether closing the view releases terminal control.
• Closing a workspace, pane, or Agent requires local confirmation. Herdr v0.8.2 cannot stop only an Agent, so Close Agent explicitly closes its pane and every process inside it.

Run managed background processes

EnableSettings→General→Managed processes

Managed background processes let the Agent keep development servers, watchers, mock APIs, and other project tasks running under the app's lifecycle control without shell &, nohup, or an external terminal. Short commands continue to use Bash.

Start and inspect a process

1. Choose a trusted project folder, then turn on Enable managed background processes under Settings → General. The feature is off by default.
2. Ask the Agent to start a development server, watch build, or another long-running task; it uses the process_* tools.
3. Open Processes on the right to inspect owner, state, readiness, redacted logs, loopback endpoints, and exit reasons.
4. Select Open in Browser for an available endpoint to debug it with the built-in Browser. Process capability and Browser authorization remain separate.

Control processes and logs

• Send line-oriented stdin, stop, force stop, or restart a process, and search, copy, or export its logs.
• Slow-starting tasks continue from a log cursor instead of rereading all output. Logs use bounded buffers and redact common secrets.
• Each process belongs only to the Agent session that started it. Restarts create a new run ID, and stale operations are rejected.
• An Agent cannot automatically bypass a user stop. A crash reaper performs bounded process-tree cleanup after Host or app failure.

Configure models

OpenSettings→Models

Pi Agent Desktop v0.2.0 includes Pi Coding Agent 0.84.0 but does not include model credits. Connect an existing model provider account or enter an API key from your provider.

Use an API key

1. Open Settings → Models and select Add provider.
2. Choose your model provider.
3. For a proxy or compatible endpoint, enter a Base URL; leave it blank to use the provider default.
4. Paste the API key and save. The app synchronizes the Agent Host model state.
5. Select a model. If a Test action is available, use it to verify the connection.
6. Close Settings and choose the model below the conversation composer.

The Base URL overrides the endpoint for the current API-key provider and takes effect with the API key after you select Save at the bottom of the page. Model catalog refresh is fully timeout-bounded: even if service creation or final catalog projection stalls, the app stops waiting and preserves the cached models.

Control which models appear

1. Open Settings → Models and choose a connected subscription or API-key provider.
2. Review the enabled count. When a provider has many models, search by model name or ID.
3. Toggle models individually, or use Enable all and Disable all for the provider.
4. Wait for the selection to save, then return to the conversation model selector.

The selection persists to Pi settings and remains compatible with existing thinking-level configuration, but it does not change the model currently used by an existing session. The app prevents a configuration with no valid models from being saved.

Refresh the model directory

1. Open the model selector below the conversation composer.
2. Select Refresh model directory to fetch the latest models from configured providers.
3. Wait for the refresh to finish. Offline, timeout, and partial-provider failures appear as a status or warning.

Sessions prefer the locally cached model directory on startup instead of making an unnecessary network request. A failed refresh never clears existing models, so the cached directory remains available.

Use OAuth

1. Choose a provider that supports OAuth.
2. Select Sign in and complete authorization in your browser.
3. Return to the app and confirm the provider shows as connected. Signing in or out automatically synchronizes the model state.

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.

Skills settings

OpenChoose a project→Settings→Skills

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

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

Plugins settings

OpenChoose a project→Settings→Plugins

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

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

Messaging channel settings

OpenSettings→Messaging channels

Choose a channel. The official QR creation flow is recommended for Feishu / Lark, while existing custom apps remain supported:

Create a Feishu / Lark bot by QR code

1. Select Connect Feishu / Lark, then choose Scan to create (recommended).
2. Select Feishu China or Lark for the account region.
3. Generate the QR code, scan it in the corresponding client, and complete official authorization.
4. The app creates the bot, configures required permissions, stores the credentials, verifies the identity, and starts the connection.

Connect an existing Feishu / Lark app

Choose Existing app, select Feishu or Lark, then enter the App ID and App Secret. The QR flow never reads an existing app's App Secret.

Finish the account setup

1. Save the account and configure its default project directory and access policy as needed.
2. Start the account and confirm its status is Running.
3. 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.

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

Manage the Herdr runtime

macOS and Linux packages include a digest-verified Herdr v0.8.2. Developer Tools shows the bundled and installed versions plus private disk usage, and lets you install, update, repair, or remove the private runtime from the bundled copy without downloading Herdr separately.

Herdr versions arrive with Pi Desktop updates. Removing the private runtime does not delete Herdr Sessions or the recovery copy bundled inside the app.

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