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

# Quickstart

> Install Ocean Code, sign in, start a session in the terminal, and know where it keeps its files.


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.

<Steps>
<Step title="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.

```bash
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](/oceancode/distribution).

</Step>
<Step title="Sign in once">

```bash
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](/oceancode/platform-mode).

</Step>
<Step title="Start a session">

```bash
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](/ocean-code/work-modes). `/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](/ocean-code/sessions-together)).

</Step>
<Step title="Or run it headless">

```bash
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](/ocean-code/editors-and-terminal)). Every subcommand with its flags is in the [CLI reference](/oceancode/cli-reference), the routes in the [HTTP API](/oceancode/http-api).

</Step>
</Steps>

## Where files live

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

| What | Location |
|---|---|
| Global config | `~/.config/oceancode/oceancode.json` (or `$OC_CONFIG`) |
| Credentials | `~/.local/share/oceancode/auth.json` |
| Session store | `oceancode.db` in the folder you started in, unless `--db <path>` is given |
| Session transcripts and ledger pages | `~/.local/share/oceancode/session-ledger/<session-id>/` |
| Project config, skills and plans | `<project>/.oceancode/` (`oceancode.jsonc`, `skills/`, `plans/`) |
| The pager's own settings | `~/.local/share/oceancode/pager/config.toml` |

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](/oceancode/capabilities), [MCP servers](/oceancode/mcp)). Every config key and environment variable has a row in the [configuration reference](/oceancode/configuration).

## A repository in Ocean Git, without a clone

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

```bash
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](/oceancode/cli-reference#oceancode-workspace).

## Next

- [Sessions that keep the thread](/ocean-code/tideline): what happens when a session grows long.
- [Long runs and sub-agents](/ocean-code/long-runs): bounds, the plan, the dock.
- [Away from the Mac](/ocean-code/slack): answer from Slack.