> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# Xcode, Zed and other ACP editors — oceancode acp

> oceancode acp runs the Ocean engine as an Agent Client Protocol (ACP) agent on the process's stdin/stdout. An ACP editor — Xcode 26.6 and later, Zed, JetBrains, Neovim — starts the binary itself as a subprocess and talks newline-delimited JSON-RPC over the pipe. There is no URL, no port and no …


`oceancode acp` runs the Ocean engine as an **Agent Client Protocol** (ACP) agent on the process's
stdin/stdout. An ACP editor — Xcode 26.6 and later, Zed, JetBrains, Neovim — starts the binary itself
as a subprocess and talks newline-delimited JSON-RPC over the pipe. There is no URL, no port and no API
key for the editor: the editor is the client, the subprocess is the agent, and the editor asks you for
consent the first time it launches it.

It uses the same ACP backend and engine as the TUI: the same model and credentials, permissions,
agents (build · plan · ask · debug), ledger and session store. The editor launches `oceancode acp`
directly; it does not route requests through the TUI or require an HTTP server. ACP agent and
Ocean extension handlers live in `crates/ocean-acp/`; the TUI is another client that embeds the
backend in-process (`crates/ocean-cli/src/acp.rs`, `crates/ocean-acp/src/stdio.rs`).

| Flag | Default | Meaning |
|---|---|---|
| `--db <path>` | `oceancode.db` | the session store |
| `--directory <dir>` | cwd | the working directory the engine starts in; the editor's `session/new` `cwd` wins per session |
| `--verbose`, `-v` | off | trace every provider request/response to stderr (credentials masked) |

**stdout is the wire.** Every byte the process writes to stdout is one JSON-RPC message; the banner,
diagnostics and tracing go to stderr. The process exits 0 when the editor closes stdin.

## Xcode

Source: Apple, [Setting up coding intelligence](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence)
— "To enable an agent that doesn't appear in Intelligence settings and supports the Agent Client
Protocol (ACP), click Add an Agent under Agents, enter information in the next sheet, and click Add."

1. Find the binary's absolute path: `which oceancode` (for example `/Users/you/.local/bin/oceancode`).
   Xcode needs the absolute path — no `~`, no relative path, and it validates nothing until first launch.
2. **Xcode › Settings › Intelligence**, under **Agents** click **Add an Agent…** and fill the sheet:

   | Field | Value |
   |---|---|
   | Name | `Ocean Code` |
   | Executable | the path from step 1 |
   | Interpreter | leave blank (`oceancode` is a native binary, not a script) |
   | Arguments | `acp` — one argument per row |
   | Environment Variables | none needed (see Credentials) |

   Click **Add**. Ocean Code now appears under Agents.
3. In the Intelligence sidebar click **New Conversation** and pick **Ocean Code**. The first time,
   Xcode asks whether to allow the agent to run — click Allow.

Do not confuse the Agents sheet with **Chat › Add a Chat Provider**: that door takes a URL (or a local
port) serving `/v1/models` and `/v1/chat/completions` plus an API key and gives a chat box without
tools. The coding agent lives behind the Agents sheet.

## Credentials

Xcode starts the agent with a bare `PATH` — the system folders only, `/usr/bin:/bin:/usr/sbin:/sbin`
(reproduced 2026-10-31 on two Macs; an earlier observation on Xcode 27 saw the login shell's `PATH`, so
this varies by Xcode build — assume the bare one). Two things follow. A credential kept in a shell variable (`ANTHROPIC_API_KEY` in
`~/.zshrc`) is never seen, so log in once from a terminal and the stored credential is used by every
Xcode session:

```bash
oceancode auth        # API key or Claude Pro/Max subscription → auth.json in the data directory
```

([01 · Getting started](/oceancode) lists the locations.) A key in `oceancode.json` works
too. And the Claude Pro/Max route probes `claude --version` on that `PATH` to learn the version it must
present; with none found it falls back to a version Anthropic may refuse (`claude_code_version_too_old`,
shown by Xcode as "Your request couldn't be completed"), and MCP servers started with `npx` or `uvx`
do not spawn. Add one row under the sheet's Environment Variables, `PATH`, with your terminal's `PATH`
(`echo $PATH`). Xcode writes the sheet's values into a plist under
`~/Library/Developer/Xcode/CodingAssistant/ACP/`, so keep secrets out of it and use the stored login.

Xcode runs the agent with `~/Library/Developer/Xcode/CodingAssistant/<agent-id>/` as its working
directory, so that is where `oceancode.db` — the transcripts of your Xcode conversations — lands;
each session's own `cwd` is the project folder Xcode hands over in `session/new`.
A TUI window opened in the project therefore never lists an Xcode session; reopen one by its code from
anywhere with `oceancode resume <code>` ([21](/oceancode/cli-reference#oceancode-resume)), or by id with
`ocean-tui --db ~/Library/Developer/Xcode/CodingAssistant/<agent-id>/oceancode.db --cwd "$PWD" --resume <session-id>`.

## Zed

Zed runs `oceancode acp` as an external agent. Add it to `~/.config/zed/settings.json`, with an explicit
`PATH` for the same reason as Xcode's:

```json
{
  "agent_servers": {
    "Ocean Code": {
      "type": "custom",
      "command": "/Users/you/.local/bin/oceancode",
      "args": ["acp"],
      "env": { "PATH": "/Users/you/.local/share/oceancode/bin:/Users/you/.local/bin:/opt/homebrew/bin:/usr/bin:/bin" }
    }
  }
}
```

Ocean Code then appears in Zed's Agent Panel, which shows one thread at a time. For several sessions
side by side, run the TUI in Zed's center-pane terminals instead: a task in `~/.config/zed/tasks.json`
that runs `oceancode` in a new terminal (concurrent runs allowed, cwd the project root), bound in
`keymap.json` to a key such as `alt-o` with `reveal_target: center`; Zed's split keys then tile as many
TUI windows as you like, each with its own `⇄N OC` chip and `#code` tab title, all on the project's
`oceancode.db` so `/status` lists them together. Set `terminal.option_as_meta` to `true` so the TUI's
`Option+Tab` reaches it, and `terminal.line_height` to `"standard"` for the box-drawing rows. Known
gaps: Zed's `/` menu is empty (the engine advertises its commands only at `initialize`; a typed `/plan`
still expands), and the `question` tool arrives as text.

## Xcode's tools

When Xcode starts a session it hands the agent its own tools — build, test, run, SwiftUI previews,
documentation search, diagnostics — as an MCP server (`xcode-tools`) in `session/new`. The engine
registers every server the editor supplies before the session is created
(`crates/ocean-acp/src/mcp_servers.rs:19`, `crates/ocean-acp/src/agent.rs:158`), so the first step
already offers them; the tools are named `xcode-tools_<Tool>` in the registry. Nothing to configure:
"build the project" in an Xcode conversation uses Xcode's build, and Xcode asks before the first
build/test tool runs, as it does for every agent.

For a session you start **outside** Xcode — the TUI, `oceancode run` — the same tools come from
Xcode's MCP bridge: in Intelligence settings turn on **Allow external agents to use Xcode tools**, then

```bash
oceancode mcp add xcode --command xcrun --arg mcpbridge
```

with the project open in Xcode ([11 · MCP](/oceancode/mcp); Apple:
[Giving external agents access to Xcode](https://developer.apple.com/documentation/xcode/giving-external-agents-access-to-xcode)).

## Permissions and questions

A tool call that needs approval becomes an ACP `session/request_permission` with allow once,
allow always, and reject choices. The shared outbound driver resolves replies and rejects them on
cancellation or disconnect (`crates/ocean-acp/src/outbound.rs`, `permission.rs`). The engine's
questionnaire tool has no equivalent in base ACP. A client that advertises Ocean's questionnaire
extension receives the structured question request; a generic ACP client receives the question
text in the transcript and the blocked tool is rejected so the model can continue conversationally.
This fallback avoids claiming that an unsupported form was shown. Xcode's actual questionnaire
behavior has not yet been validated in its UI. Always-approve and the Shift+Tab agent ring are
reachable through the editor's mode picker where it has one; Xcode exposes the session modes it is
given (build · plan · ask · debug).

## Verify by hand

Two requests on stdin, one reply or notification per line on stdout, exit 0 at EOF — no Xcode needed.
Hold stdin open for a moment: the host returns as soon as the pipe closes, and a request still in
flight at that instant is dropped (an editor keeps the pipe open for the life of the conversation).

```bash
{ printf '%s\n' \
    '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' \
    '{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"'"$PWD"'","mcpServers":[]}}'
  sleep 3
} | oceancode acp 2>/dev/null
```

The first line answers with `agentCapabilities` (`loadSession`, `mcpCapabilities.http/sse`), the last
with a `sessionId` plus the model and mode lists; between them an `_ocean/sessions/changed`
notification — an Ocean extension the TUI uses and a plain ACP client ignores. Add a
`session/prompt` line with that id to see the turn stream as `session/update` notifications. This is
what `crates/ocean-cli/tests/acp_mode.rs` pins on every build.

## See also

- [19 · Ocean TUI](/oceancode/tui) — the terminal UI on the same engine.
- [07 · Headless and server](/oceancode/headless-and-server) — `serve`, `run`, `goal`, `workflow`.
- [12 · Permissions and sandbox](/oceancode/permissions-and-sandbox) — the rules behind every approval prompt.
