Ocean Documentation

Ocean is the platform and trust layer for coding agents. It gives teams using Claude, Codex, Cursor, Gemini, and other agents isolated workspaces, validation evidence, spend control, PR status, and safe merge paths before code reaches production.

Download for macOS

Ocean is available for macOS on Apple Silicon. Download the current release from GitHub.

Installation

macOS (Apple Silicon)

1. Download the latest release from the Releases page
2. Extract the archive:

   tar -xzf Ocean_*_aarch64.app.tar.gz

3. Move Ocean.app to your Applications folder:

   mv Ocean.app /Applications/

4. On first launch, macOS may block the app. Open System Settings > Privacy & Security and click Open Anyway, or run:

   xattr -cr /Applications/Ocean.app

5. Double-click Ocean.app to launch

Getting Started

When Ocean launches, you'll see a single session in the Default workspace. From there you can create isolated agent sessions, connect a repository, organize work into projects, and monitor status from the sidebar and top status bar.

The Interface

┌──────────────────────────────────────────────────────┐
│  NetworkIndicator   SystemMetrics         GitStatus  │  Status Bar
├──────────┬───────────────────────────────────────────┤
│ SESSIONS │  ● Shell 1                                │  Pane Header
│          │                                           │
│ Default  │  ~ $                                      │  Terminal
│ ● Shell 1│                                           │
│ ● Shell 2│                                           │
│          │                                           │
│ Settings │                                           │
├──────────┴───────────────────────────────────────────┤
│ docker ● │ flutter ● │ node ●                        │  Connectors
└──────────────────────────────────────────────────────┘

• Sidebar (left): Workspaces and sessions
• Terminal area (center): Active shell and agent panes
• Status bar (top): System metrics, network, git info
• Connector bar (bottom): Detected dev tools

Sessions

Sessions are individual terminal instances, each running its own shell process.

• Rename: Double-click the session name in the sidebar
• Closed sessions: Move to the Closed section. Click to view scrollback history.

Split Panes

Work on multiple things side by side within the same tab.

Sidebar Indicators

Sessions sharing a split show direction-aware badges:

Resizing

• Drag the divider between panes
• Click ⇔ in the pane header to auto-resize to your configured width
• Up to 5 panes per tab

Workspaces

Workspaces group sessions around a project or repository. Repo workspaces are the main unit for isolated agent development, git tracking, merge review, and PR shipping.

• WS button: Create a blank workspace
• Repo button: Create a workspace linked to a git repository
• Copy Workspace Path: Right-click the workspace header to copy the Ocean workspace directory at ~/.ocean/workspaces/{id}

Repo Workspaces

When linked to a git repo, workspaces show:

• Branch name, ahead/behind counts in the pane header
• Staged, modified, and untracked file counts
• Ship to PR capability (Cmd+Shift+S)

Projects

Projects organize related workspaces in the sidebar. They are local to your machine and are not synced through team relay.

Keyboard Shortcuts

Pro Tip: Use Cmd+Shift+P at any time to open the Command Palette. It's the fastest way to discover and run any command in Ocean.

Essential

Git

Merge & Conflicts

Panels

All shortcuts are searchable in Settings > Commands tab.

Command Palette

Cmd+Shift+P opens the command palette — a searchable list of every command, shortcut, and saved snippet.

Cmd+P opens the quick switcher to jump to any session by name.

Terminal History

Cmd+Shift+H opens the history panel showing commands across all sessions.

• Type to search
• Enter to re-run a command
• Exit codes shown: [SUCCESS], [ERROR] failure with code

Snippet Library

Cmd+Shift+E opens the snippet library for saved commands.

• Name: Descriptive label
• Command: Shell command (supports ${variable} templates)
• Category: general, dev, git, docker, etc.

Run snippets from the library or from the command palette.

AI Agent Detection

Ocean detects AI coding agents running in your sessions:

Detected agents show a colored badge in the pane header. View all agents in the Agent Dashboard (Cmd+Shift+J).

Git Visualizer

Cmd+Shift+V opens the Git Visualizer showing:

• Staged, modified, and untracked files
• File diffs
• Staging controls

Pull Request Runtime

Ocean tracks pull request status for repo workspaces in the background using your existing gh CLI authentication. It refreshes branch and PR state on a 30 second interval.

Useful commands include track_workspace_pr, refresh_workspace_pr, and get_workspace_pr_status. The frontend receives pr-status-update events.

Conflict Resolution

When multiple sessions edit the same files, Ocean detects and resolves conflicts automatically.

How It Works

Each session runs in its own copy-on-write clone of the workspace. When you merge a session back, Ocean:

1. Detects conflicts at the file and line level
2. Classifies severity: disjoint (auto-merge safe), overlapping (review), or conflicting (manual)
3. Shows a merge panel with inline diffs and per-hunk resolution controls

Merge Panel

Open with Cmd+Shift+M when conflicts are detected. The conflict banner at the top shows the count.

AI-Assisted Merge

Click AI Suggest on any conflict to get a Claude-powered merge suggestion with a confidence score. Review the result and accept, edit, or dismiss.

Requires ANTHROPIC_API_KEY environment variable. See the Configuration section for details.

Supporting Features

Port Forwarding

Share local ports publicly using built-in tunneling.

Right-click a detected port in the Ports Panel to create a tunnel via:

• Bore (lightweight, open-source)
• Cloudflared (Cloudflare)

Ocean auto-installs the tunnel provider on first use.

File Workflows

Ocean has native path workflows for feeding files into agents without manually typing long paths.

Agent Notifications

Ocean monitors AI agents running in your sessions and notifies you when they need input:

• Pane header turns yellow after 30 seconds of agent waiting
• Desktop notification if the window is not focused
• View all agent states in the Agent Dashboard (Cmd+Shift+J)

Usage Quota

Usage quota tracks cumulative estimated Codex spend across sessions and helps teams avoid surprise AI costs.

• Configure warning and error thresholds in Settings > General > Usage Quota
• See the quota bar in the status bar
• Receive notifications when spend crosses configured thresholds
• Quota state is stored locally under ocean:usage-quota

Plugins

Ocean supports a three-tier plugin system: MCP servers, WASM sandbox plugins, and native Rust plugins. Installed plugins live under ~/.ocean/plugins/ and declare an ocean-plugin.toml manifest.

Team Relay

Team relay is an optional collaboration backend. Ocean works standalone by default; connect relay only when a team wants shared workspace capabilities or a self-hosted sync endpoint.

• Configure relay in Settings > Team
• The server URL is configuration, not a secret, and can be overridden for self-hosted deployments
• JWT and refresh tokens are read from macOS Keychain only when the Team tab restores a session
• relay_login, relay_register, relay_logout, and relay_restore_session handle auth from the app

Settings

Open with Cmd+, or the gear icon in the sidebar.

Configuration

Ocean can be configured via environment variables, per-workspace env vars, localStorage settings, plugins, or the built-in settings panel.

Environment Variables

Articles

Understand Ocean from the perspective that matters to you. Browse all articles →

Use Cases

Multi-Agent Development

Run Claude Code in one pane, Codex in another, Cursor or Gemini in another, and a manual shell in a fourth. Ocean tracks each agent with status badges and keeps their work isolated.

┌────────────────┬────────────────┐
│ ● Claude Code  │ ● Aider        │
│ Working on     │ Refactoring    │
│ auth module... │ tests...       │
├────────────────┴────────────────┤
│ ● Shell                         │
│ ~/project $ git status          │
└─────────────────────────────────┘

Microservice Development

Create a workspace per service. Each workspace holds sessions for servers, logs, and tests.

▼ API Service       3 sessions
  ● Server  ● Tests  ● Logs
▼ Frontend          2 sessions
  ● Dev Server  ● Build
▼ Database          1 session
  ● Migrations

Feature Branch Workflow

1. Create a repo workspace (click Repo)
2. Split panes for code + tests
3. Monitor git status in pane headers
4. Review changes in Git Visualizer (Cmd+Shift+V)
5. Check review and CI state in the PR status detail panel
6. Ship to PR (Cmd+Shift+S)

Debugging with History

1. Run your failing command
2. Open history (Cmd+Shift+H) to find previous runs
3. Compare exit codes and timing
4. Click to re-run from history

Data and Privacy

Ocean runs standalone on your machine. No terminal content or commands leave your device unless you explicitly configure a team relay or plugin that performs network requests.

Troubleshooting

App won't open on macOS

xattr -cr /Applications/Ocean.app

Terminal shows blank screen

Quit and relaunch the app. If it persists, delete ~/.ocean/ocean.db and restart.

Sessions missing after restart

Ocean respawns sessions automatically. If a session's directory was deleted, it won't respawn. Create a new session with Cmd+T.

Shortcut not working

Open Cmd+Shift+P and search for the action. Some shortcuts may conflict with macOS system shortcuts.

PR status is not updating

Confirm the workspace is linked to a GitHub repo, the branch has a pull request, and gh is authenticated in your shell.

Team login restores the wrong server

Open Settings > Team, confirm the server URL, then restore the session. Ocean syncs the configured URL before reading tokens from Keychain.

Downloads

Get the latest version from the Releases page or download from here!