Ocean Documentation

Ocean is a high-performance terminal reimagined for the AI era. It provides a safe, isolated environment where AI agents can work autonomously without risking your project's stability.

Join the Waitlist

Ocean is currently in private beta for macOS (Apple Silicon).

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 terminal session in the Default workspace.

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 terminal 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 under a project.

• WS button: Create a blank workspace
• Repo button: Create a workspace linked to a git repository

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)

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

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.

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)

Settings

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

Configuration

Ocean can be configured via environment variables 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, Aider in another, and a manual shell in a third. Ocean tracks each agent with status badges.

┌────────────────┬────────────────┐
│ ● 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. 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 entirely on your machine. No terminal content or commands leave your device.

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.

Downloads

Get the latest version from the Releases page.