Ocean pager reference

This page lists Ocean pager's slash commands, keyboard shortcuts, mode ring, config.toml settings, themes and notification options. For how the pager starts, its environment variables and what is wired to the Ocean engine, see Ocean pager.

Slash commands

Type / in the composer to open the menu. A prefix narrows the list, and Tab or Enter inserts the command. Enabled skills appear in the same menu (19 · Ocean pager).

In the Needs column, session means an active session, fullscreen or minimal means that screen mode only (in the other mode the command tells you to switch), and dashboard means the Agent Dashboard. args means the command needs an argument.

Session and conversation

Ocean engine controls

These commands use _ocean/* methods. For their argument forms, see 19 · Ocean session commands.

Model, context and output

Extensions and workflows

Settings and display

Navigation, help and maintenance

Keyboard

The defaults live in a single registry. Keys apply where the Where column says: prompt when the composer has focus, scrollback when the conversation has focus (Tab switches between them), agent anywhere on the agent screen, and global everywhere. Ctrl+. (or Ctrl+X) opens the full cheatsheet.

Essentials

Prompt

The double-press window is 800 ms (OC_PAGER_ESC_DOUBLE_PRESS_MS overrides it).

Panes and sessions

Scrollback

Bare-letter keys in this table work only when vim_mode is on (/vim-mode). Arrows, PgUp/PgDn, Enter, Tab, ? and every Ctrl chord always work.

Agent Dashboard

Mouse

Click a pane to focus it. The wheel and trackpad scroll the pane (see the scroll_* settings), and you can click or drag the scrollbar. In-app selection and double-click follow keep_text_selection; hold Shift while dragging to use the terminal's own selection. Queued prompts have [Interject], [edit] and [cancel] buttons. Double-clicking a [Pasted: N lines] chip expands it into editable text.

Work-mode picker

F4 or a bare /mode opens it in the prompt's place: the modes on the left (Model first, tagged default; custom diagrams after a ── custom ── divider; on a narrow terminal the labels only) with the highlighted mode's description under them, cut with … when it runs out of rows, and its picture and cost on the right. The footer names the keys, e: copy too when the width allows (23 · Work modes).

Every mode but Model puts its badge on the prompt's top border, after the ultracode badge when that is on: solo, delegate ≤4, pair, pipeline, orchestrate ≤8, goal, race ×3, and for Auto auto until its first pick, then auto → <pick> · <reason>. Model has no badge.

Modes (Shift+Tab ring)

Shift+Tab cycles Build → Auto → Plan → Ask → Debug → Build. Build, Plan, Ask and Debug are the engine's agents; Auto is a permission stop that keeps the Build agent and sets the auto permission mode. The prompt border shows the current mode in its color:

The ring skips the Auto stop while always-approve is on, or when auto mode is not available. Leaving Auto writes permission_mode = "ask" back. What each permission mode allows is in 19 · Shift+Tab ring and permission modes.

Settings (config.toml)

The settings modal (/settings, F2) edits these settings. Unless the Key column gives another table, each is written to the [ui] table of <pager home>/config.toml ($OC_PAGER_HOME). Restart means the change takes effect on the next start. Rows in the modal's Hidden in minimal set still apply to the full TUI.

Appearance

Mouse

Editor, agent and models

Agent defaults (its own section, after Models) has two rows per ring agent: <Agent> model (a catalog model, or (no override)) and <Agent> effort (inherit, minimal, low, medium, high, xhigh, max). They are not pager settings: each change is an _ocean/agents call that writes agents.<id>.model / agents.<id>.effort into the user oceancode.json (~/.config/oceancode/oceancode.json, the rows fleet-router edits too), and inherit / (no override) write "". Shift+Tab to that agent applies them, the effort clamped to the levels the model offers (19, 02). A write the engine refuses (an oceancode.json that does not parse, say) shows as agent defaults not saved: … and changes nothing. Each ring agent also has a work-mode row: a mode id, saved through _ocean/mode as agents.<id>.mode in the same user file (23).

Sub-agents (its own section) has three number rows, at once, per turn and depth: the sub-agent limits subagent.max_concurrent (0–64), subagent.max_per_turn (1–1000) and subagent.max_depth (1–4), written to the user oceancode.json through _ocean/mode. A set number wins over the work mode's own limit in every mode; an out-of-range one is refused with the engine's message (23).

[ui.contextual_hints] holds the per-hint switches. All default to true, and the modal shows them as one Show contextual hints group: undo (Ctrl+Z restores a cleared prompt), plan_mode (suggests plan mode for a planning request), image_input (offers to paste a clipboard image), send_now (empty-prompt Enter sends the top queued item), small_screen (suggests /compact-mode), word_select, export_copy (points out /copy and /export) and ssh_wrap (a /doctor tip over SSH).

Two modal rows are not saved. multiline_mode (default false) resets each session, and plan_mode (off/on, default off) is per session.

Keys outside the modal

Themes

Names are case-insensitive. On a terminal without truecolor, the themes that need it are not offered. The pre-rename keys groknight, grok-night, grokday and grok-day still load, for one release. OC_PAGER_THEME forces a theme without editing the config.

Notifications

Desktop notifications, the tab title and the progress indicator are set in [ui.notifications]:

Protocol selection (method = "auto"). The pager picks the protocol from the terminal:

Under tmux the sequence is wrapped in DCS passthrough, so it reaches the outer terminal. Control characters are stripped from the text first. The progress indicator is drawn only on Ghostty, WezTerm and iTerm2 3.6 or later.

Custom commands. Each [[ui.notifications.hooks]] entry runs command through sh -c for its events. The command gets OC_PAGER_EVENT, OC_PAGER_MESSAGE and OC_PAGER_SESSION_ID. only_unfocused defaults to true, and timeout_secs defaults to 10 (minimum 1); a hook that runs past its timeout is killed.

[[ui.notifications.hooks]]
command = "terminal-notifier -title 'Ocean Code' -message \"$OC_PAGER_MESSAGE\""
events = ["turn_complete", "approval_required"]

/notify. /notify toggles desktop notifications, and /notify on or /notify off sets them. Off sets method to none for the running pager. On restores the method you had before, or auto. It does not write config.toml.

See also

• Ocean pager: the binary, the environment variables, and what is wired to the engine
• Permissions and sandbox: what each permission mode allows
• Session ledger and export: the tideline behind /tideline
• Plan mode and todos: /plan and the todo pane
• Bounding a long run: /budget and /limits