Use
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 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 (opens in a new tab) — "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."
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.Xcode › Settings › Intelligence, under Agents click Add an Agent… and fill the sheet:
Field Value Name Ocean CodeExecutable the path from step 1 Interpreter leave blank ( oceancodeis a native binary, not a script)Arguments acp— one argument per rowEnvironment Variables none needed (see Credentials) Click Add. Ocean Code now appears under Agents.
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:
oceancode auth # API key or Claude Pro/Max subscription → auth.json in the data directory(01 · Getting started 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), 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:
{
"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
oceancode mcp add xcode --command xcrun --arg mcpbridgewith the project open in Xcode (11 · MCP; Apple: Giving external agents access to Xcode (opens in a new tab)).
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).
{ 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/nullThe 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 — the terminal UI on the same engine.
- 07 · Headless and server —
serve,run,goal,workflow. - 12 · Permissions and sandbox — the rules behind every approval prompt.