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

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.

# 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, 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.

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 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 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 and 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 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 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.
• 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 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 routes all file operations to Zed's in-memory buffers first. The read and write tools in src/tools/read.ts and 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 and processed through the event mapper in src/modes/acp/acp-event-mapper.ts to ensure Zed receives proper notifications and updates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}