Reference
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.
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).
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) | 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). 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) | session |
Ocean engine controls
These commands use _ocean/* methods. For their argument forms, see
19 · 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) | 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 | — | 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); edit <name> <what to change> asks it to change one of yours (24) | 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) | — |
/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) |
Option+Tab / F3 | prompt | Cycle reasoning effort for this session |
F4 | agent | Open the 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) |
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 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; 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). 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).
| 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).
| 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).
| 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.
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) |
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) |
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, 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), 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). What each one turns off:
12 · 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.
[[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: 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:
/planand the todo pane - Bounding a long run:
/budgetand/limits