Quickstart

Ocean Code is two self-contained binaries installed side by side: the engine oceancode and the terminal UI ocean-pager it launches. There is no Node, no Python and no daemon.

1. 1
   Install

   A release tarball carries both binaries and an install.sh that checks every file against its checksum, clears the download quarantine and installs into ~/.local/bin (set OC_INSTALL_DIR for another folder). If that folder is not on your PATH, the installer prints the line to add.

   tar -xzf oceancode-<version>-macos-aarch64.tar.gz
   cd oceancode-<version>-macos-aarch64 && sh install.sh
   oceancode --version

   From a checkout, cargo install --locked --path crates/ocean-cli builds and installs it with the Rust toolchain alone. Later, oceancode update fetches the newest release for your channel, verifies it and swaps both binaries atomically, rolling back on failure. The channels, the signature and checksum trust model and oceancode verify-release are in the distribution reference.

2. 2
   Sign in once
   oceancode auth                      # interactive: an API key or a Claude Pro/Max subscription
   oceancode login                     # Claude Pro/Max subscription, non-interactive
   oceancode key <key>                 # store an Anthropic API key
   oceancode key openai <key>          # another provider's key, same file
   oceancode login --provider ocean    # your Plunge account, through the browser

   The credential is written to auth.json in the data directory and reused on every later run; a Plunge sign-in keeps its refresh token in the macOS keychain and never prints a token. oceancode key alone reports what is stored. With a Plunge sign-in, model calls go through the gateway (ocean/<provider>/<model>) and are billed to your account's wallet; see platform mode.

3. 3
   Start a session
   cd your-project
   oceancode

   Plain oceancode opens Ocean pager on a fresh session in the current folder. Type at the prompt. Shift+Tab cycles the agent: Build, then Auto (edits run without a card), Plan, Ask and Debug; the prompt border names the current one. F4 opens the work-mode picker. /resume lists earlier sessions in this folder; from any folder, oceancode resume <code> reopens a session by its four-character code or by words from its title (sessions together).

4. 4
   Or run it headless
   oceancode run "summarise the README"      # one job, then exit
   oceancode serve                           # the HTTP surface on port 4096
   oceancode acp                             # the engine as an editor agent on stdin/stdout

   run prints the result and exits with a typed code; serve exposes sessions, prompts and status over HTTP for your own tooling; acp is what Xcode and Zed launch (editors). Every subcommand with its flags is in the CLI reference, the routes in the HTTP API.

Where files live

Paths follow the XDG layout on every platform, macOS included (~/.config, not ~/Library).

A project's CLAUDE.md or AGENTS.md, its .claude/skills/, Cursor rules and MCP servers are found and loaded as they are; nothing has to be rewritten for Ocean Code (capabilities, MCP servers). Every config key and environment variable has a row in the configuration reference.

A repository in Ocean Git, without a clone

A folder can work on a repository that lives in Ocean Git with nothing checked out:

oceancode workspace init ocean-git://<repo>@<branch> my-work --handle <handle>
cd my-work && oceancode

The agent's read, glob, grep and apply_patch go through Ocean Git; materialize fetches the files a build or a test needs onto disk; land commits the changes back as one commit, from the agent or with oceancode workspace land -m "…". A workspace of 1.8 MB stands in for a 630 MB clone. Details in the CLI reference.

Next

• Sessions that keep the thread: what happens when a session grows long.
• Long runs and sub-agents: bounds, the plan, the dock.
• Away from the Mac: answer from Slack.