pi-ahp

pi-ahp is an Agent Host Protocol host for the pi coding agent.

It embeds pi and makes its sessions available to AHP clients over WebSocket. Interoperability is primarily tested with Agent Host support in Visual Studio Code and Agent Console for iPhone and iPad, but the host is not limited to either client.

The project is under active development; expect rough edges and occasional instability. Contributions are welcome.

Requirements

• Node.js 24 or later
• At least one model provider configured for pi

Usage

npm install --global pi-ahp

pi-ahp starts a direct WebSocket listener and prints its connection URL:

pi-ahp

On first run, it creates ~/.pi/ahp/settings.json with a free port and a random token, for example:

{
  "host": "127.0.0.1",
  "port": 32145,
  "token": "<generated token>"
}

PI_AHP_DIR overrides the pi-ahp data directory and must be absolute.

The token is optional and may be set to null. The host and port can also be overridden for one run:

pi-ahp --host 127.0.0.1 --port 31546

Enter the printed URL in any AHP client. The direct listener is bring-your-own-network: reach it through Tailscale, SSH port forwarding, a reverse proxy, or any other network you manage. Keep the connection token enabled whenever the listener is reachable beyond localhost.

pi-ahp-tunnel instead creates or reuses a Microsoft Dev Tunnel for clients that support it, including VS Code and Agent Console. It requires the devtunnel CLI and does not use the direct-listener settings:

devtunnel user login
pi-ahp-tunnel

Run either command with --help for all available options.

Visual Studio Code

VS Code exposes remote Agent Host setup only in its dedicated Agents window, not in a regular editor window. From a regular window, run Chat: Open Agents Window.

If the remote-host commands are unavailable, or if you want to use a direct connection without signing in to GitHub, add these settings to VS Code's user settings.json before opening the Agents window:

{
  "chat.remoteAgentHostsEnabled": true,
  "chat.agentHost.allowSignedOutWhenUsable": true
}

The signed-out option is currently experimental and desktop-only. When prompted, choose Continue Without Signing In; you do not need to preconfigure a host manually.

• Direct WebSocket: run Agents: Add Remote Agent Host... and paste the URL printed by pi-ahp.
• Dev Tunnel: sign in to the same account in VS Code, then run Agents: Connect to Remote Agent Host via Dev Tunnel. Tunnel discovery requires sign-in.

iPhone and iPad

I also make Agent Console, a paid native AHP client for iPhone and iPad. Purchasing it helps support continued work on both Agent Console and pi-ahp.

Agent Console connects with the direct URL printed by pi-ahp, or through a tunnel created by pi-ahp-tunnel when signed in to the same Dev Tunnels account. pi and its model credentials remain on the host, and Agent Console has no hosted backend. See the Agent Console setup guide for Pi Coding Agent for details.

AHP support

The following is a high-level mapping to the official AHP specification.

Currently supported protocol versions: 0.9.0

🟢 Supported · 🟡 Planned · 🔴 Out of scope

| Feature | Status | Notes | | --- | :---: | --- | | Connection lifecycle and reconnect | 🟢 | Active work survives a temporary connection loss, but not a host restart | | Durable sessions and history | 🟢 | Completed history for the active conversation branch recovers after restart | | Streaming chat and pi tool calls | 🟢 | One chat per session | | Steering, queues, drafts, and truncation | 🟢 | Drafts and unconsumed queues do not survive a host restart | | Models, session setup, and completions | 🟢 | Model and thinking-level selection, working directory, and @ file completions | | Text attachments | 🟢 | Client-provided text, local file references, and embedded UTF-8 text | | Files and watches | 🟢 | Host-local file: resources only | | Interactive terminals | 🟢 | Client-owned; terminals and scrollback end when the host stops | | Images and vision | 🟢 | Embedded image attachments for vision-capable pi models | | Changeset views | 🟢 | Latest commit and uncommitted changes in Git workspaces | | Tool catalogue and client tools | 🟡 | Show available pi tools and let connected clients contribute tools | | pi customizations | 🟡 | Show and configure loaded extensions, skills, and prompt templates | | Terminal command detection | 🟡 | Group terminal output by command and exit status | | Persistent archive controls | 🟢 | Host-owned metadata, stored separately from pi session files | | Persistent read controls | 🟡 | Historical sessions are currently reported as read | | Multiple chats or working directories | 🔴 | A pi session has one active branch and cwd; branches are not simultaneous AHP chats | | Custom agents | 🔴 | pi sub-agents are extension tools rather than selectable agents | | Elicitation | 🔴 | pi extension dialogs are not persisted as turn input | | Tool input and result confirmation | 🔴 | pi has no built-in permission policy | | Errored-turn resume | 🔴 | pi cannot reopen a finalized turn | | MCP lifecycle and Apps | 🔴 | pi has no built-in MCP runtime; extension implementations are opaque | | Annotations | 🔴 | There is no corresponding pi session state | | Automations and automation runs | 🔴 | pi has no scheduler or automation-run model | | AHP protected-resource authentication | 🔴 | pi manages model-provider credentials itself | | OTLP telemetry channels | 🔴 | pi does not provide host telemetry as OTLP |

License

MIT