OceanCode guide

oceancode is one binary and one process. This page builds it, shows the two ways to start it, and lists where it keeps its files.

Build

cargo build --release -p ocean-cli

The binary is named oceancode and, because the workspace builds into a shared target directory, it lands at the repository-root target/release/oceancode (that is ../../target/release/oceancode from this app directory). Put it on your PATH or call it by that path.

The three boot shapes

oceancode starts in one of three shapes, chosen by the subcommand.

Shape	Command	What runs
Pager	`oceancode`	Ocean pager (`ocean-pager`) with the Ocean engine in the same process over ACP — the terminal UI. See 19 · Ocean pager.
Editor	`oceancode acp`	The engine as an Agent Client Protocol agent on stdin/stdout — what Xcode and other ACP editors launch as a subprocess. See 20 · Xcode and other ACP editors.
Headless	`oceancode serve`, or a non-interactive subcommand (`run`, `goal`, `workflow`, `ledger`, `export`, …)	The engine only, no UI: `serve` exposes the HTTP surface, the others run one job and exit.

# 1. Pager + engine (the usual way)
oceancode

# 2. Headless server on port 4096
oceancode serve

# 3. One headless run
oceancode run "summarise the README"

The default mode accepts --db, --directory, --listen and --verbose (-v) and passes them to the engine. --tui pager is accepted for compatibility and changes nothing; --tui ocean fails with "the native TUI was removed; oceancode starts Ocean pager". Binding beyond loopback needs --listen and a server password; see 07 · Headless and server.

First run

Authenticate once, then start a session.

oceancode auth        # interactive: API key or Claude Pro/Max subscription
# or, non-interactively:
oceancode login       # Claude Pro/Max subscription login
oceancode key <key>   # store an Anthropic API key

The credential is written to auth.json in the data directory (below) and reused on every later run. Then launch oceancode and type at the prompt.

oceancode key <provider> <key> stores another provider's key in the same file — oceancode key typesafe <key> stores a TypeSafe key, which turns on the Jev decision layer (13 · Jev decisions); oceancode key alone reports what is stored.

Starting a session

A plain oceancode opens the pager on a fresh session. Earlier sessions are listed and resumed from inside the pager — see its own user guide under ocean-pager/crates/ocean-pager-ui/docs/user-guide/. Headless runs pick a session with oceancode run --continue / --session <id>; see 07 · Headless and server.

Updating and removing

Keep the binary current, verify a download, or remove it:

oceancode update                 # update to the newest release for your channel (verified, atomic, rollback on failure)
oceancode verify-release oceancode-macos-aarch64.tar.gz   # check a download's signature before trusting it
oceancode uninstall              # remove the binary (add --purge to also remove config + data)

See 17 · Distribution and updates for install one-liners, channels, and the signature/checksum trust model.

Where files live

Paths follow the XDG layout on every platform (macOS included — ~/.config, not ~/Library). <x> below is the matching $XDG_*_HOME when set, otherwise the home-relative default shown.

What	Location
Global config	`$OC_CONFIG`, else `<XDG_CONFIG_HOME \| ~/.config>/oceancode/oceancode.json`
Credentials	`<XDG_DATA_HOME \| ~/.local/share>/oceancode/` — `auth.json`
Models catalog cache	`<XDG_CACHE_HOME \| ~/.cache>/oceancode/models.json`
Session database	`oceancode.db` in the working directory, unless `--db <path>` is given
Project config and assets	`<project>/.oceancode/` — `oceancode.jsonc`, `oceancode.json`, `skills/`, `plans/`

02 · Configuration — the config keys and environment variables.
19 · Ocean pager — the terminal UI; its slash commands and keys are in ocean-pager/crates/ocean-pager-ui/docs/user-guide/.