# How to Set Up ACP Integration with the Zed Editor for Oh-My-Pi

> Set up ACP integration with Zed editor. Build oh-my-pi, run it with --mode acp, and configure Zed to use the executable for seamless ACP support.

- Repository: [Can Bölük/oh-my-pi](https://github.com/can1357/oh-my-pi)
- Tags: how-to-guide
- Published: 2026-05-21

---

**To enable ACP integration with the Zed editor, build the `omp` binary from the can1357/oh-my-pi repository, launch it with `--mode acp`, and configure Zed's "Agent Client Protocol" settings to use that executable with the `--mode acp` argument.**

The **Agent Client Protocol (ACP)** allows the Oh-My-Pi coding agent to run headlessly and communicate directly with compatible editors. By setting up ACP integration with the Zed editor, you can drive the agent's capabilities—including file editing, terminal commands, and model switching—directly from Zed's UI without using the terminal interface. This guide covers the complete setup process using the actual source implementation from `can1357/oh-my-pi`.

## Building and Running the ACP Server

First, you need the `omp` binary that implements the ACP server. You can build it from source or download a pre-built release from the GitHub releases page.

```bash

# Build the binary

bun run build

# Run the agent in ACP mode (uses STDIO by default)

./omp --mode acp

```

The entry point for ACP mode is [`src/modes/acp/acp-agent.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/modes/acp/acp-agent.ts), which creates the `AcpAgent` class. This server remains stateless until a session is created, allowing it to complete `initialize` and `authenticate` steps before any model is selected according to the changelog in [`packages/coding-agent/CHANGELOG.md`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/CHANGELOG.md).

## Configuring Zed for ACP Integration

Once the binary is ready, configure Zed to connect to it:

1. Open **Zed Settings**
2. Navigate to **Agent Client Protocol**
3. Set the following values:

| Field | Value |
|-------|-------|
| **Executable** | `/full/path/to/omp` |
| **Arguments** | `--mode acp` |
| **Transport** | `STDIO` (default) or `TCP` (if using `--port 8765`) |

After saving, Zed launches the binary (or attaches to a running process) and displays a connection status. When using TCP transport, start the server with `./omp --mode acp --port 8765` and select TCP in Zed's transport settings.

## Understanding the ACP Architecture

### The AcpAgent Entry Point

The `AcpAgent` class in [`src/modes/acp/acp-agent.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/modes/acp/acp-agent.ts) serves as the main entry point for ACP mode. It creates a **client-bridge** (`ClientBridge`) that inspects the ACP initialize payload to determine which capabilities the connected editor supports. The server uses `ACP_BOOTSTRAP_RACE_GUARD_MS` to protect against race conditions that cause "Received session notification for unknown session" errors in Zed logs (see lines 1450-1453).

### Client-Bridge Routing

The `ClientBridge` implementation in [`src/session/client-bridge.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/session/client-bridge.ts) abstracts communication between the agent and the connected editor. It routes tool I/O for file operations, terminal execution, and permission prompts to Zed. This bridge guarantees that the editor's **in-memory buffer** remains the source of truth for `read` and `write` calls, preventing race conditions between unsaved changes and disk reads.

### Capability-Based Tool Dispatch

When Zed advertises capabilities during initialization, the agent adapts its behavior:

- **File System** – If `fs.readTextFile` or `fs.writeTextFile` are advertised, the tools in [`src/tools/read.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/tools/read.ts) and [`src/tools/write.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/tools/write.ts) call `clientBridge.fsRead` and `clientBridge.fsWrite` first, falling back to disk I/O only if the bridge errors.
- **Terminal** – When the `terminal` capability is present, the bash tool in [`src/tools/bash.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/tools/bash.ts) creates a client-side terminal, embeds a `terminalId` in the tool card, polls for output, and releases the handle on exit.
- **Permission Gate** – The `requestPermission` capability enables `session/request_permission` prompts for destructive tools (bash, edit, write, ast_edit), with the bridge remembering "allow always" or "reject always" decisions for the session lifetime.

## Enabling File System and Terminal Bridging

To leverage the full integration capabilities, ensure Zed advertises the optional features during the ACP handshake. When enabled, all file system operations route through Zed's buffers rather than direct disk access. This means:

- Reading a file retrieves the current buffer content, including unsaved changes
- Writing a file updates the buffer first, maintaining consistency with the UI
- Terminal commands execute in Zed's integrated terminal with proper session management

The event mapper in [`src/modes/acp/acp-event-mapper.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/modes/acp/acp-event-mapper.ts) ensures all ACP notifications (config updates, model changes, plan mode toggles, tool-call updates) emit stable message IDs and absolute paths, allowing Zed to open files directly from agent responses.

## Verifying the ACP Connection

After configuration, verify the integration by checking Zed's status bar for "Connected to ACP server" and the current model or session display. The connection is working correctly when:

- Zed shows the connected status indicator
- The agent logs show successful initialization without bootstrap race warnings
- Zed's command palette recognizes Oh-My-Pi slash commands

If you see suppressed notifications in Zed's logs regarding unknown sessions, this indicates the bootstrap guard is functioning correctly to handle initialization timing.

## Using ACP Commands in Zed

All TUI slash commands are mirrored as ACP RPCs, accessible directly from Zed's command palette (`⌘⇧P`). Key mappings include:

- `/model` → `session/set_model`
- `/todo` → `session/todo`
- `/move` → corresponding movement RPC

These commands are documented in the CHANGELOG (lines 314-321) and handled by the event mapper to ensure Zed receives proper notifications. When you execute `/model gpt-4o`, Zed sends the `session/set_model` RPC, and the agent responds with a `config_option_update` notification that updates the UI.

## Summary

- Build or install the `omp` binary from the can1357/oh-my-pi repository to access the ACP server implementation.
- Launch the agent in ACP mode using `./omp --mode acp` to start the STDIO or TCP server defined in [`src/modes/acp/acp-agent.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/modes/acp/acp-agent.ts).
- Configure Zed's Agent Client Protocol settings with the executable path and `--mode acp` argument to establish the connection.
- Verify the connection status in Zed's UI and check that the bootstrap guard handles session initialization cleanly.
- Use Zed's command palette to execute all TUI slash commands as ACP RPCs, with file and terminal operations routing through the client-bridge.

## Frequently Asked Questions

### What is the Agent Client Protocol (ACP) in Oh-My-Pi?

ACP is a communication protocol implemented in [`src/modes/acp/acp-agent.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/modes/acp/acp-agent.ts) that allows the Oh-My-Pi agent to run as a headless server and accept commands from compatible editors like Zed. It exposes the agent's functionality—including file tools, terminal access, and model management—through standardized RPCs instead of the terminal-based TUI.

### How does Oh-My-Pi handle file system operations through Zed?

When Zed advertises `fs.readTextFile` and `fs.writeTextFile` capabilities during initialization, the `ClientBridge` in [`src/session/client-bridge.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/session/client-bridge.ts) routes all file operations to Zed's in-memory buffers first. The read and write tools in [`src/tools/read.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/tools/read.ts) and [`src/tools/write.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/tools/write.ts) check the bridge before falling back to disk I/O, ensuring unsaved changes in the editor don't create race conditions with disk state.

### Can I run the ACP server over TCP instead of STDIO?

Yes, while STDIO is the default transport for `./omp --mode acp`, you can start the server with `./omp --mode acp --port 8765` to listen on TCP. In Zed's ACP settings, change the transport setting from STDIO to TCP and specify the corresponding port number to establish the network connection instead of standard I/O streams.

### Which commands are available when using Oh-My-Pi through ACP in Zed?

All TUI slash commands are available as ACP RPCs, including `/model` (mapped to `session/set_model`), `/todo`, and `/move`. These commands are exported according to the ACP subcommand documentation in [`packages/coding-agent/CHANGELOG.md`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/CHANGELOG.md) and processed through the event mapper in [`src/modes/acp/acp-event-mapper.ts`](https://github.com/can1357/oh-my-pi/blob/main/src/modes/acp/acp-event-mapper.ts) to ensure Zed receives proper notifications and updates.