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

# Ocean TUI reference

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


This page lists Ocean TUI's slash commands, keyboard shortcuts, mode ring, `config.toml` settings, themes and
notification options. For how the TUI starts, its environment variables and what is wired to the Ocean engine,
see [Ocean TUI](/oceancode/tui).

## 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 TUI](/oceancode/tui#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; the name is yours and no automatic name replaces it. `--auto` returns to the automatic title, which the next real prompt sets once | session, args |
| `/delete` | — | Delete this session | session |
| `/session-info` | — | Show session info | session |
| `/btw <question>` | — | Ask a side question without interrupting the turn. It is answered from the conversation so far (your messages, the replies and the tool results, all but the reply still being written), by one reply without tools; question and answer are not added to the conversation, and a later `/btw` sees the earlier ones | session, args |
| `/recap` | `/summarize` | Show a one-line recap of what this session is working on and where it stands; one small model call, nothing is added to the conversation | 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 |
| `/status [all \| <code \| words>]` | — | The board of every Ocean Code session on this machine (`_ocean/status`), as `oceancode status` prints it | session |
| `/slack [on \| off]` | — | Slack Remote on or off for every window on this Mac (`_ocean/slack`); bare flips it ([24 · Slack](/oceancode/slack#turning-it-on-and-off)) | session |
| `/peers [take <path \| name:label>]` | — | Bare, opens Messages on its Sessions tab (every session on this machine, with the three switches' states); `take` gives a claim another session holds to this session (`_ocean/peers`). Messages are answered in Messages (Enter, `d`) | session |
| `/messages [#code <message>]` | `/message`, `/msg` | Bare: opens Messages on its Inbox tab, the messages between sessions (Enter accepts, `d` declines, `w` takes back one accepted here) and, on the Sessions tab, every session (Enter writes to it); the same window as a click on `[Messages]` or the session row ([19 · Messages](/oceancode/tui#messages)). With a code and text: sends that session a message, toasted `Sent rN to #code`; typing `/message ` pops up the sessions | session |
| `/continue` | — | After `/pause`: check the provider answers, then let every agent go on (`_ocean/continue`). Otherwise carry on where this session left off: queues the prompt built from its open plan rows, interrupted tool calls and a last turn that stopped before it finished | session |
| `/pause` | — | Hold every agent and sub-agent before its next model call (`_ocean/pause`); `Paused` on the status bar until `/continue` ([19 · Pause before you go offline](/oceancode/tui#pause-before-you-go-offline)) | session |

### Ocean engine controls

These commands use `_ocean/*` methods. For their argument forms, see
[19 · Ocean session commands](/oceancode/tui#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, a workflow id turns that workflow on and keeps the mode, `default` clears both (`_ocean/mode`, [23](/oceancode/work-modes#mode-and-workflow-together)) | 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: tokens, spend, and the session's speed (first token, round trip and tool time as p50 · p95 · last) | — |
| `/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` | — | The workflow picker: turn one on, Auto or Off; write or change one ([Workflow picker](#workflow-picker)) | — |
| `/workflow` | — | Launch a saved workflow, list runs, or manage a run (pause, resume, stop, save); `new <description>` asks the agent to write a YAML workflow ([24](/oceancode/workflows#writing-your-own)); `edit <name> <what to change>` asks it to change one of yours ([24](/oceancode/workflows#changing-one)) | 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; a second `Ctrl+C` right after it quits |
| `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 | Stops the turn, as `Ctrl+C` does; with sub-agents running, the stop card asks whether they stop too. An open card or overlay takes the `Esc` first |

The double-press window is 800 ms (`OC_TUI_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_TUI_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; on a question card, back to chat with your answers so far ([19 · Question cards](/oceancode/tui#question-cards)) |
| `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. On a message the agent has not read yet, `[cancel]` takes it back, and `[edit]` opens it in the prompt: Enter
sends the changed text, Esc sends it as it was. Once the agent has read a message, both answer
`Too late: the agent already has this message`. 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, at most 24 rows tall: the modes on the left (Model first,
tagged `default`; your own modes after a `── custom ──` divider; on a narrow terminal the labels only), the
highlighted mode's picture on the right, and under both, across the whole width, its description, `when to use` and
`cost`, cut with `…` when it runs out of rows. It lists ways of working only; workflows are in `/workflows`, laid out
the same way ([Workflow picker](#workflow-picker)). When the session's workflow setting is not off, the title row
names it (`Workflow: Auto · /workflows to change`). 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 and the text follow 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.yaml` 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, at the left after the agent and the `ultracode`
badge when that is on:
`solo`, `delegate ≤4`, `pair`, `orchestrate ≤8`, `spec ×3`, `build`, `review ×3`, `secure ×4`, `research`, `goal`,
`race ×3`, and for Auto `auto` until its first pick, then `auto → <pick> · <reason>`. While a workflow's run is
active the badge adds the task it is on: `spec ×3 · validate`. Model has no badge.
With workflow Auto on and a mode other than Auto, the border adds `workflow auto` after the mode's badge until a pick
is made for the prompt.

### Workflow picker

`/workflows` opens it in the prompt's place, laid out as the work-mode picker. The title reads `Which workflow?`, with
`Mode: <label> · F4 to change` on the right of the title row. The rows: **Off**, **Auto**, the built-in workflows
(Spec, Build, Review, Secure, Research, Goal, Race), your own files A–Z after a `── yours ──` divider, and
**Build your own…** last. `●` marks the session's setting, where the cursor opens, and `○` the rest; `default` tags
the default for new sessions. The footer names the keys that apply to the highlighted row
([24 · Workflows](/oceancode/workflows#the-workflow-picker)).

| Keys | Action |
|---|---|
| `Down` / `Up` (`j` / `k`) | Move; the picture and the text follow at once |
| `Enter` | Turn the row on for this session (Auto or one workflow) and close; on Off, turn the workflow off; on **Build your own…**, close and put `/workflow new ` in the prompt |
| `d` | Make it the default for new sessions (`workflow` in the user `oceancode.json`); on the current default, clear it |
| `e` | On one of yours, close and put `/workflow edit <name> ` in the prompt; on a built-in, first write your copy `.oceancode/workflows/<name>-copy.yaml` (or take the copy already listed as yours) and fill `/workflow edit <name>-copy ` |
| `o` | Close and open the workflow in the workflow editor (a built-in read-only); on **Build your own…**, a starter |
| `Esc` | Close |

### Workflow editor

`o` in `/workflows` opens a workflow's YAML over the conversation, with line numbers, colours, the diagram on the right
from 100 columns, the errors of the last check under the text, a status row and the keys on the last row. It takes
every key while open; `Ctrl+Q` still quits. The file is held for you while it is open
([24 · Workflows](/oceancode/workflows#editing-by-hand)).

| Keys | Action |
|---|---|
| `Ctrl+S` (`Alt+S`) | Check and save; a refused text is not written and the cursor goes to the first error's line |
| `Ctrl+T` | Check only |
| `Tab` / `Shift+Tab` | Indent or outdent the line or the selected lines by two spaces |
| `Enter` | New line at the same indent, two more after `key:` |
| `PageUp` / `PageDown`, `Ctrl+Home` / `Ctrl+End` | Move a screen; go to the start or the end |
| `Esc` | Close; with unsaved changes, a second `Esc` closes |
| Click | In the text, place the cursor (drag to select); on an error, go to its line |

## 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/tui#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 `<TUI home>/config.toml` (`$OC_TUI_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-tui` 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 (`edit`, `write` and `apply_patch` alike). `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_TUI_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_TUI_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 scrolling; off keeps about 60 Hz. A streaming answer is repainted at most 30 times a second either way (`OC_TUI_MIN_DRAW_MS`). Restart |
| `respect_manual_folds` | bool | `false` | Keep manually folded blocks as they are while streaming (experimental). Written to `tui.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 TUI updates on startup. Restart. When `oceancode` launches the TUI, auto-update is always off ([19](/oceancode/tui)) |

**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
TUI 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/tui#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), `send_now` (empty-prompt `Enter` sends the top queued item), `word_select`, `export_copy`
(points out `/copy` and `/export`) and `ssh_wrap` (a `/doctor` tip over SSH). The clipboard-image and small-screen
hints were removed; an `image_input` or `small_screen` key left in an older config is ignored.

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

### Messaging

The three switches for how sessions work together, and the only place they are changed. The engine owns them: each
row shows the engine's current value, and a change goes through `_ocean/peers` and is written to your user
`oceancode.json` (`peers.*`). Messages shows their states on its status line, and `s` there opens F2 at this
section ([19 · Messages](/oceancode/tui#messages)). What each one turns off:
[12 · Switching it off](/oceancode/permissions-and-sandbox#switching-it-off).

| Key | Row | Default | Meaning |
|---|---|---|---|
| `peers.awareness` | See other sessions | on | Show the other Ocean Code sessions on this Mac and tell the agent when they touch its files. Write protection stays on |
| `peers.requests` | Messages between sessions | on | Let other sessions send this window messages, and let its agent send them |
| `peers.machines` | Share with other machines | on | Share claims with other machines through the project's hub (`.oceancode/ocean-hub.json`) |

### 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_TUI_MOUSE_REPORTING_TOGGLE` overrides it) |
| `[cli] session_picker_grouped` | bool | on | Group the session picker |
| `[dashboard] enabled` | bool | `true` | Enable `/dashboard` (`OC_TUI_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_TUI_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. `OC_TUI_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` | `false` | Show an automatic recap when you come back after being away. Off by default because each recap is one model call; `/recap` works either way |
| `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 TUI 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_TUI_EVENT`, `OC_TUI_MESSAGE` and `OC_TUI_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_TUI_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 TUI. On restores the method you had before, or `auto`. It does not write
`config.toml`.

## See also

- [Ocean TUI](/oceancode/tui): 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`
