> ## 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.

# 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.


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](/oceancode/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](/oceancode/pager#what-is-wired-to-the-ocean-engine)).

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

| Command | Aliases | What it does | Needs |
|---|---|---|---|
| `/new` | `/clear` | Start a new session | — |
| `/resume` | — | Resume a previous session | — |
| `/fork [--worktree\|--no-worktree] [directive]` | — | Branch the current session into a peer agent | session |
| `/rename <title> \| --auto` | `/title` | Rename the current session; `--auto` returns to the automatic title | session, args |
| `/delete` | — | Delete this session | session |
| `/session-info` | — | Show session info | session |
| `/btw <question>` | — | Ask a side question without interrupting the turn | session, args |
| `/recap` | `/summarize` | Summarize the session so far; listed only when session recap is available | session |
| `/rewind` | `/undo` | Rewind the conversation, and the files the file tools changed, to a previous turn | session |
| `/redo` | — | Re-apply the turn a rewind reverted, files included (`ocean/restore_code`) | session |
| `/compact [instructions]` | — | Compact the conversation history (`ocean/compact_conversation`) | session |
| `/queue` | — | List the prompts queued behind the running turn | session |
| `/history` | — | Search prompt history | session |
| `/loop [interval] <prompt>` | — | Run a prompt on a recurring interval | args |
| `/plan [description]` | — | Enter plan mode; `add`/`done`/`cancel`/`edit`/`remove` edit the live todo table (`_ocean/todos/set`) | session |
| `/view-plan` | `/show-plan`, `/plan-view` | View the current plan | session |
| `/share` | — | Share this session via a public URL (`ocean/share_session`); hidden from the menu until enabled, but you can still type it | session |
| `/unshare` | — | Revoke this session's share link (`ocean/unshare_session`) | session |

### Ocean engine controls

These commands use `_ocean/*` methods. For their argument forms, see
[19 · Ocean session commands](/oceancode/pager#ocean-session-commands).

| Command | Aliases | What it does | Needs |
|---|---|---|---|
| `/tideline [now \| <n>% \| <tokens> \| default]` | `/shelve` (hidden) | Show or set the Session Ledger tideline (`_ocean/ledger/status`) | session |
| `/retention [<days> \| off]` | — | Show or set how many days idle sessions are kept — one setting for the database and the ledger, written to the global config (`_ocean/retention`) | session |
| `/budget [<usd> \| off \| subscription]` | — | Show or set this session's spend bound (`_ocean/session/bounds`) | session |
| `/limits [steps <n\|default> \| time <dur\|off>]` | — | Show or set the per-turn step and time bounds (`_ocean/session/bounds`) | session |
| `/subagent [<provider/model> \| default \| off \| clear]` | — | Show or set the sub-agent model (`_ocean/subagent_model`) | session |
| `/mode [<id> \| default]` | — | Bare opens the work-mode picker (as `F4`); `<id>` sets this session's work mode, `default` clears it (`_ocean/mode`, [23](/oceancode/work-modes)) | session |

### Model, context and output

| Command | Aliases | What it does | Needs |
|---|---|---|---|
| `/model <name> [effort]` | `/m` | Switch the active model | session, args |
| `/effort <level>` | — | Set reasoning effort for the current model | session, args |
| `/connect <provider>` | — | Connect a model provider (API key or account login) | args |
| `/context` | — | View context usage | session |
| `/usage` | `/cost` | View usage | — |
| `/copy [N] [file]` | — | Copy the last response (or the Nth) to the clipboard or a file | session |
| `/export [filename]` | — | Export the current conversation to a file or the clipboard | session |
| `/transcript` | `/log` | View the conversation transcript in `$PAGER` | session |
| `/find [text]` | — | Search the conversation scrollback | session, fullscreen |
| `/jump` | — | Jump to a turn in the conversation | session, fullscreen |
| `/expand` | — | Re-print the last collapsed block, fully expanded | session, minimal |
| `/edit-prompt` | — | Open an external editor for an empty prompt (to keep a draft, use the command palette) | session |

### Extensions and workflows

| Command | Aliases | What it does | Needs |
|---|---|---|---|
| `/skills` | — | View skills | — |
| `/plugins` | `/plugin` | View plugins | — |
| `/hooks` | — | View hooks | — |
| `/mcps` | — | Show MCP server status | — |
| `/marketplace` | — | View the marketplace | — |
| `/workflows` | — | Browse installed workflows | — |
| `/workflow` | — | Launch a saved workflow, list runs, or manage a run (pause, resume, stop, save) | session |

### Settings and display

| Command | Aliases | What it does | Needs |
|---|---|---|---|
| `/settings` | `/config`, `/preferences`, `/prefs` | Open the settings modal | — |
| `/theme [name]` | `/t` | Switch the color theme | fullscreen |
| `/auto` | — | Toggle auto mode (a classifier approves safe tools); listed only when auto mode is available | — |
| `/always-approve` | — | Toggle always-approve (skips all permission prompts) | — |
| `/vim-mode` | — | Toggle vim-style scrollback keys | — |
| `/multiline` | `/ml` | Toggle multiline input (swaps `Enter` and `Shift+Enter`) | — |
| `/compact-mode` | — | Toggle compact UI (less padding) | — |
| `/timestamps` | — | Toggle message timestamps | — |
| `/timeline` | — | Toggle the timeline sidebar | fullscreen |
| `/notify [on \| off]` | — | Toggle desktop notifications ([Notifications](#notifications)) | — |
| `/toggle-mouse-reporting` | — | Toggle terminal mouse reporting, so the terminal's own click-drag copy works | — |
| `/minimal` | — | Switch this session to minimal (scrollback-native) mode | session, fullscreen |
| `/fullscreen` | `/full` | Switch this session to fullscreen mode | session, minimal |

### Navigation, help and maintenance

| Command | Aliases | What it does | Needs |
|---|---|---|---|
| `/dashboard` | `/agents-dashboard`, `/sessions` | Open the Agent Dashboard; listed only when the dashboard is enabled | fullscreen |
| `/cd [path]` | — | Change the working directory for new agents | dashboard |
| `/home` | `/welcome` | Return to the welcome screen | — |
| `/help` | — | Browse commands and keyboard shortcuts | — |
| `/docs [web\|title]` | `/howto`, `/guides` | Open the in-TUI how-to guides, or (`web`) the published developer guide, `https://code.plungeai.com/docs`, in the browser | — |
| `/release-notes` | `/changelog` | View release notes for the current version | — |
| `/doctor [fix [FIX]]` | `/terminal-setup`, `/terminal-check`, `/terminal-info` | Check this session and show the fixes available | session |
| `/quit` | `/exit` | Quit Ocean Code (asks first) | — |
| `/debug [scroll\|fps\|log]` | — | Toggle debug overlays; listed only on debug builds | — |
| `/scroll-debug` | — | Toggle the scroll-diagnostics HUD; never listed | — |

## 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

| Keys | Where | Action |
|---|---|---|
| `Enter` | prompt | Send |
| `Ctrl+Enter` (alt `Ctrl+I`) | prompt | Send now while a turn runs: cancels the current turn and sends the message next. In Apple Terminal it is `Ctrl+O`; in VS Code-family terminals, `Ctrl+L` |
| `Tab` | prompt / scrollback | Focus the scrollback / focus the prompt (`i` or `Space` also focus the prompt) |
| `Ctrl+C` | agent | Cancel the turn |
| `Shift+Tab` | prompt | Cycle the mode ring ([Modes](#modes-shifttab-ring)) |
| `Option+Tab` / `F3` | prompt | Cycle reasoning effort for this session |
| `F4` | agent | Open the work-mode picker ([Work-mode picker](#work-mode-picker)) |
| `Ctrl+O` | agent | Toggle always-approve |
| `Ctrl+P` (alt `?`) | agent | Command palette: search every action and slash command by name |
| `Ctrl+.` (alt `Ctrl+X`) | agent | Keyboard shortcuts. Where `Ctrl+.` is unreliable (Windows, WSL, some terminals) the two keys swap |
| `Ctrl+M` | agent | Pick a model (when the prompt has focus, `Ctrl+M` toggles multiline instead) |
| `F2` (alt `Ctrl+,`, `Cmd+,`) | agent | Open the settings modal |
| `Ctrl+N` | global | New session |
| `Ctrl+Q` (alt `Ctrl+D`) | global | Quit; press twice in quick succession. In VS Code's terminal, `Ctrl+D` only |

### Prompt

| Keys | Where | Action |
|---|---|---|
| `Ctrl+M` | prompt | Toggle multiline |
| `Ctrl+S` (alt `Alt+S`) | prompt | Stash the draft; on an empty composer, pop it back. A new stash replaces the old one |
| `!` | prompt | Shell mode (type it on an empty prompt) |
| `Up` | prompt | Browse prompt history (empty prompt). `/history` opens the search panel |
| `Esc` `Esc` | prompt | With text and no turn running: clear the prompt (`Ctrl+Z` restores it) |
| `Esc` `Esc` | prompt / scrollback | With an empty prompt and at least one turn: open the rewind picker |
| `Esc` | while a turn runs | Never cancels; a toast names the cancel key |

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

### Panes and sessions

| Keys | Where | Action |
|---|---|---|
| `Ctrl+T` | agent | Toggle the todo pane |
| `Ctrl+G` | agent | Hide or show the dock above the prompt (the tasks pane at the top with `OC_PAGER_DOCK=0`). In minimal mode, edit the prompt in `$VISUAL` / `$EDITOR` (`vi` if neither is set) |
| `Ctrl+B` | agent | Send the running task to the background |
| `Ctrl+;` (alt `Ctrl+'`) | agent | Toggle the prompt queue. In VS Code-family terminals on a local Mac, `Ctrl+4` |
| `Ctrl+R` | agent | Open sessions |
| `Ctrl+L` | agent | Open extensions (unbound in VS Code-family terminals; use `/plugins`) |
| `Ctrl+\` (alt `Ctrl+4`) | global | Open the Agent Dashboard |

### Scrollback

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

| Keys | Action |
|---|---|
| `j` / `k` (`Down` / `Up`) | Select the next / previous entry |
| `L` / `H` (`Shift+Right` / `Shift+Left`) | Next / previous turn |
| `J` / `K` | Jump to the next / previous turn at the top of the viewport |
| `g` / `G` | Go to the top / bottom |
| `Ctrl+K` / `Ctrl+J` | Scroll up / down one line |
| `Ctrl+U` / `Ctrl+D` | Scroll up / down half a page (in VS Code, `D` scrolls down) |
| `PgUp` / `PgDn` | Scroll one page |
| `h` / `l` (`Left` / `Right`) | Collapse / expand the selected entry |
| `e` / `E` | Expand or collapse the entry / every entry |
| `Ctrl+E` | Toggle all thinking blocks |
| `r` | Toggle raw markdown |
| `y` / `Y` | Copy the content / the command or path |
| `Enter` (alt `Ctrl+F`) | Open the entry in the viewer |
| `o` / `O` | Next / previous link |
| `x` | Kill the selected background task |
| `Ctrl+R` | Toggle mouse reporting, only when `[ui] mouse_reporting_toggle` is on (it then replaces Open sessions while the scrollback has focus) |

### Agent Dashboard

| Keys | Action |
|---|---|
| `Down` / `Up` (`j` / `k` with vim mode) | Select the next / previous row |
| `Shift+Down` / `Shift+Up` | Move the agent down / up |
| `Shift+Tab` | Cycle the dispatch mode |
| `Ctrl+T` | Pin / unpin the agent |
| `Ctrl+R` | Rename the agent |
| `Ctrl+X` | Stop / delete the agent |
| `Ctrl+O` | Toggle always-approve for the selected agent |
| `Ctrl+G` | Toggle row grouping |
| `Ctrl+L` | Change the working directory for new agents |
| `Ctrl+W` | Toggle worktree mode for new agents |
| `Ctrl+.` (or `?`) | Show the shortcuts overlay |
| `Esc` | Close the dashboard |
| `Ctrl+\` | (inside an attached session) Back to the dashboard |
| `Ctrl+[` / `Ctrl+]` | (inside an attached session) Previous / next session |
| `Ctrl+X` | (inside an attached session) Stop the agent and go back to the 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`](#settings-configtoml); 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](/oceancode/work-modes)).

| Keys | Action |
|---|---|
| `Down` / `Up` (`j` / `k`) | Move; the picture follows at once |
| `Enter` | Use the mode for this session and close |
| `d` | Make it the current agent's default (`agents.<id>.mode` in the user `oceancode.json`) and close |
| `e` | Copy the highlighted built-in to `.oceancode/modes/<id>-copy.jsonc` and close; the toast names the path |
| `Esc` | Close without a change |

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:

| Mode | Border |
|---|---|
| `build` | blue |
| `auto` | yellow |
| `plan` | violet |
| `ask` | green |
| `debug` | orange |
| `always-approve` | red |

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](/oceancode/pager#shifttab-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

| Key | Type | Default | Meaning |
|---|---|---|---|
| `theme` | enum | `oceannight` | Color theme ([Themes](#themes)) |
| `auto_dark_theme` | enum | `oceannight` | Theme used in system dark mode (only with `theme = "auto"`) |
| `auto_light_theme` | enum | `oceanday` | Theme used in system light mode (only with `theme = "auto"`) |
| `screen_mode` | `fullscreen` \| `minimal` | `fullscreen` | How plain `ocean-pager` opens next time. Restart. `/minimal` and `/fullscreen` switch only the current session |
| `compact_mode` | bool | `false` | Less padding around messages. Turns on automatically at 20 terminal rows or fewer |
| `show_timestamps` | bool | `true` | Clock time next to user messages and agent responses |
| `show_timeline` | bool | `false` | A per-turn tick rail in place of the scrollbar; hover to preview, click to jump |
| `page_flip_on_send` | bool | `true` | Scroll a sent prompt to the top of the screen so the response starts on a fresh page |
| `simple_mode` | bool | `true` | Plain readline-style input in the prompt instead of vim keys (vim input is experimental) |
| `vim_mode` | bool | `false` | Vim keys for navigating the scrollback; the prompt is unaffected |
| `render_mermaid` | `auto` \| `on` \| `off` | `auto` | `auto`/`on` show a clickable row that opens the rendered diagram; `off` shows the raw source |
| `max_thoughts_width` | int 40–500 | `120` | Column width of the thoughts panel |
| `show_thinking_blocks` | bool | `true` | Show thinking blocks while streaming |
| `group_tool_verbs` | bool | `true` | Fold consecutive read/search/list tool calls and subagent rows into one summary row |
| `show_edit_details` | bool | `true` | Show each edit's diff inline under its header. `false` shows a one-line `+N/−M` diffstat and merges back-to-back edits to the same file; expand a row to see the diff. `OC_PAGER_SHOW_EDIT_DETAILS` overrides it |
| `show_run_details` | bool | `true` | When a Run finishes, show the command and the first lines of its output with a `… +N lines` fold; `false` leaves finished runs as a header-only row. `OC_PAGER_SHOW_RUN_DETAILS` overrides it |
| `collapsed_edit_blocks` | bool | (unset) | Legacy, not in the modal: read only while `show_edit_details` is unset, as its inverse (`collapsed_edit_blocks = true` ≡ `show_edit_details = false`) |
| `[ui.display_refresh] auto_cadence_enabled` | bool | `true` | Match the display's refresh rate when streaming and scrolling; off keeps about 60 Hz. Restart |
| `respect_manual_folds` | bool | `false` | Keep manually folded blocks as they are while streaming (experimental). Written to `pager.toml` under `[scrollback.scroll]`, not `config.toml` |

### Mouse

| Key | Type | Default | Meaning |
|---|---|---|---|
| `scroll_speed` | int 1–100 | `50` | Wheel and trackpad speed multiplier |
| `scroll_mode` | `auto` \| `wheel` \| `trackpad` | `auto` | Force wheel or trackpad behavior when detection misreads your device |
| `scroll_lines` | int 1–10 | `3` | Lines per scroll tick; until you set it, each terminal's own profile applies |
| `invert_scroll` | bool | `false` | Reverse the vertical scroll direction |
| `keep_text_selection` | `flash` \| `hold` \| `word_select` | `flash` | `flash` clears the selection after mouse-up, `hold` keeps it until `Esc`, a click or a scroll, and `word_select` makes a double-click select a word and a triple-click a paragraph |

### Editor, agent and models

| Key | Type | Default | Meaning |
|---|---|---|---|
| `combine_queued_prompts` | bool | `false` | Merge consecutive plain follow-ups into one model turn |
| `confirm_before_rewind` | bool | `true` | Ask before rewinding code and conversation |
| `permission_mode` | `default` \| `ask` \| `auto` \| `always-approve` | `ask` | The permission mode; the `Shift+Tab` ring and `Ctrl+O` write it too |
| `remember_tool_approvals` | bool | `true` | Offer "Always allow" options on permission prompts. Restart |
| `default_selected_permission` | `always_allow_all_sessions` \| `allow_command_always` \| `allow_once` \| `reject` | `always_allow_all_sessions` | The option the cursor starts on in a permission prompt |
| `[toolset.ask_user_question] timeout_enabled` | bool | `true` | The `ask_user_question` tool times out instead of waiting forever. Restart |
| `[models] default` | model | (none) | The model for new sessions; changing it also switches the active session |
| `fork_secondary_model` | model | (none) | The model for the secondary agent when you fork; clearing it restores the built-in default |
| `hunk_tracker_mode` | `off` \| `agent_only` \| `all_dirty` | `off` | Which file changes are tracked as hunks; `off` also turns off line-count stats. Restart |
| `[cli] show_tips` | bool | `true` | The tip-of-the-day banner on startup. Restart |
| `[cli] auto_update` | bool | `true` | Download pager updates on startup. Restart. When `oceancode` launches the pager, auto-update is always off ([19](/oceancode/pager)) |

**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](/oceancode/pager#shifttab-ring-and-permission-modes), [02](/oceancode/configuration)). 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](/oceancode/work-modes)).

**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](/oceancode/work-modes#limits)).

`[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

| Key | Type | Default | Meaning |
|---|---|---|---|
| `[ui] require_plan_approval` | bool | `false` | The plan viewer always asks before leaving plan mode |
| `[ui] mouse_reporting_toggle` | bool | `false` | Bind `Ctrl+R` in the scrollback to toggle mouse reporting (`OC_PAGER_MOUSE_REPORTING_TOGGLE` overrides it) |
| `[cli] session_picker_grouped` | bool | on | Group the session picker |
| `[dashboard] enabled` | bool | `true` | Enable `/dashboard` (`OC_PAGER_AGENT_DASHBOARD=0` turns it off) |

## Themes

| Name | Display name | Notes |
|---|---|---|
| `oceannight` | Ocean Night | Default. A neutral dark theme with a magenta accent. Aliases `ocean-night`, `dark` |
| `oceanday` | Ocean Day | A light theme. Aliases `ocean-day`, `light`, `day` |
| `tokyonight` | Tokyo Night | Needs truecolor. Aliases `tokyo-night`, `tokyo` |
| `rosepine-moon` | Rose Pine Moon | Needs truecolor. Aliases `rosepine`, `rose-pine`, `rose-pine-moon` |
| `oscura-midnight` | Oscura Midnight | Needs truecolor. Alias `oscura` |
| `terminal` | Terminal | Uses the terminal's own background and text colors. Offered only when the terminal theme is enabled (`OC_PAGER_TERMINAL_THEME`). Aliases `terminal-default`, `transparent`, `native` |
| `auto` | Auto | Follows the system's dark/light appearance and picks `auto_dark_theme` or `auto_light_theme`. Alias `system` |

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]`:

| Key | Default | Meaning |
|---|---|---|
| `method` | `auto` | `auto`, `osc9`, `osc99`, `osc777`, `bel` or `none` |
| `condition` | `unfocused` | `unfocused` (only once the terminal has lost focus), `always` or `never` |
| `idle_threshold_secs` | `3` | How many seconds the terminal must be unfocused before a notification fires |
| `events` | `["turn_complete", "approval_required"]` | Also available: `session_ready`, `task_complete`, `agent_error` |
| `sleep_prevention` | `true` | Keep the machine from idle-sleeping during a turn (macOS IOKit assertion, Linux `systemd-inhibit`) |
| `progress_bar` | `true` | Show a progress indicator in the tab (OSC 9;4) |
| `session_recap` | `true` | Show an automatic recap when you come back after being away |
| `session_recap_threshold_secs` | `30` | How many seconds unfocused count as "away" for the automatic recap |
| `[ui.notifications.title] enabled` | `true` | Set the terminal/tab title to reflect the agent's state |
| `[ui.notifications.title] items` | `["action-required", "spinner", "activity", "session-name", "ocean"]` | Also available: `cwd`, `model`, `turn-timer` |

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

| Terminal | Protocol |
|---|---|
| iTerm2, WezTerm, Warp | OSC 9 |
| Kitty | OSC 99 |
| Ghostty, VTE, Terminator, foot | OSC 777 (titled "Ocean Code") |
| Zellij (any terminal), and every other terminal | BEL |

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.

```toml
[[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](/oceancode/pager): the binary, the environment variables, and what is wired to the engine
- [Permissions and sandbox](/oceancode/permissions-and-sandbox): what each permission mode allows
- [Session ledger and export](/oceancode/session-ledger-and-export): the tideline behind `/tideline`
- [Plan mode and todos](/oceancode/plan-mode-and-todos): `/plan` and the todo pane
- [Bounding a long run](/oceancode/bounding-a-long-run): `/budget` and `/limits`