For AI agents: an index of this guide is available at https://www.plungeai.com/guide/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. The developer documentation is at https://www.plungeai.com/docs/llms.txt.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.
Feedback

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.

ShapeCommandWhat runs
TUIoceancodeOcean TUI (ocean-tui), the terminal interface, with the Ocean engine in the same process over ACP. See 19 · Ocean TUI.
Editoroceancode acpThe 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.
Headlessoceancode 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. TUI + 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 tui is accepted for compatibility and changes nothing; --tui ocean fails with the native TUI was removed on 2026-10-05; `oceancode` starts Ocean TUI (drop `--tui ocean` / `OC_TUI=ocean`). 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 TUI on a fresh session. Earlier sessions are listed and resumed from inside the TUI (/resume, 19 · Ocean TUI), or from any folder with oceancode resume <code> (Several sessions, one Mac). 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.

WhatLocation
Global config$OC_CONFIG, else <XDG_CONFIG_HOME | ~/.config>/oceancode/oceancode.json
Credentials<XDG_DATA_HOME | ~/.local/share>/oceancode/ — auth.json
Session line<XDG_DATA_HOME | ~/.local/share>/oceancode/line/ — messaging.db (the record), addr (port and token, mode 0600), lock
Models catalog cache<XDG_CACHE_HOME | ~/.cache>/oceancode/models.json
Session databaseoceancode.db in the working directory, unless --db <path> is given
Project config and assets<project>/.oceancode/ — oceancode.jsonc, oceancode.json, skills/, plans/

Next