pi-acp Documentation

You can use slash commands within your ACP client to control the pi agent. Commands are categorized into three types:

1. File-based commands (Prompts)

These are loaded from your local filesystem:

• User commands: ~/.pi/agent/prompts/**/*.md
• Project commands: <cwd>/.pi/prompts/**/*.md

2. Built-in commands

• /compact [instructions...] – Run pi compaction (with optional custom instructions).
• /autocompact on|off|toggle – Toggle automatic compaction.
• /export – Export the current session to HTML in the session cwd.
• /session – Show session stats (tokens, messages, cost, session file).
• /name <name> – Set the session display name.
• /queue all|one-at-a-time – Set the pi queue mode (unstable).
• /changelog – Print the installed pi changelog.
• /steering – Get/set pi Steering Mode.
• /follow-up – Get/set pi Follow-up Mode.

3. Skill commands

If skills are enabled in your pi settings, they appear as /skill:skill-name in the ACP client.

Note: Slash commands provided by pi extensions are not currently supported.

To use pi-acp with an ACP client like Zed, you can choose from several installation methods. Ensure you have pi (v0.80.4+) installed and available on your PATH before proceeding.

Using ACP Registry (Recommended for Zed)

In Zed, run the zed: acp registry command and select the pi ACP adapter. This automatically configures your settings.json.

Using npx (No global install)

Add this configuration to your Zed settings.json to always run the latest version:

"agent_servers": {
  "pi": {
    "type": "custom",
    "command": "npx",
    "args": ["-y", "pi-acp"],
    "env": {}
  }
}

Global Install

Install the package globally via npm:

npm install -g pi-acp

Then configure your client:

"agent_servers": {
  "pi": {
    "type": "custom",
    "command": "pi-acp",
    "args": [],
    "env": {}
  }
}

From Source

Build the project and point your client to the dist/index.js file:

npm install
npm run build

"agent_servers": {
  "pi": {
    "type": "custom",
    "command": "node",
    "args": ["/path/to/pi-acp/dist/index.js"],
    "env": {}
  }
}

The pi_terminal_login method allows users to configure API keys or log in via an interactive terminal session.

For clients like Zed, the authentication method includes a _meta['terminal-auth'] object. This object contains a launch specification (command and arguments) that the client uses to trigger the terminal interface.

When the terminal login is triggered, the command executed is typically:

1. The current Node.js executable running the script: node <path-to-index.js> --terminal-login
2. Or, if the above is not detectable, the fallback command: pi-acp --terminal-login

// Conceptual shape of the terminal auth method returned by getAuthMethods()
{
  "id": "pi_terminal_login",
  "name": "Launch pi in the terminal",
  "description": "Start pi in an interactive terminal to configure API keys or login",
  "type": "terminal",
  "args": ["--terminal-login"],
  "env": {},
  "_meta": {
    "terminal-auth": {
      "command": "node",
      "args": ["/path/to/dist/index.js", "--terminal-login"],
      "label": "Launch pi"
    }
  }
}

Slash commands in pi-acp are defined as Markdown files located in specific directories. This allows you to create reusable prompt templates that can be invoked using the /command syntax.

Command Locations

Commands are loaded from two primary locations:

1. User Commands: ~/.pi/agent/prompts/**/*.md (Global across all projects).
2. Project Commands: <project-root>/.pi/prompts/**/*.md (Specific to the current working directory).

Command Structure

Each .md file represents a command. The filename (without the .md extension) becomes the command name. You can use YAML frontmatter to provide a custom description.

• Name: Derived from the filename.
• Description: Taken from the description key in the YAML frontmatter. If no frontmatter is present, the first line of the file is used as the description (truncated to 60 characters).
• Content: The body of the Markdown file, which serves as the prompt template.
• Source Label: Automatically appended to the description to indicate origin, e.g., (user), (user:subdir), (project), or (project:subdir).

Example Markdown File

Create a file at ~/.pi/agent/prompts/refactor.md:

---
description: Refactors the provided code for readability
---

Refactor the following code using best practices:

$@