For AI agents: an index of this guide is available at https://www.plungeai.com/guide/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. The developer documentation is at https://www.plungeai.com/docs/llms.txt.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.
Feedback

Ocean TUI is the terminal interface of oceancode. A plain oceancode execs Ocean TUI (ocean-tui); the TUI and the Ocean engine run in one process over typed ACP channels — no HTTP between UI and engine. --db, --directory, --listen and --verbose are passed through.

The native TUI, the first-party ratatui UI, was removed on 2026-10-05 (its guide pages are in archive/native-tui/docs/). For compatibility --tui tui and OC_TUI=tui are accepted and change nothing. Any other value is refused: --tui classic with unknown --tui "classic": only `tui` exists, and --tui ocean / OC_TUI=ocean with the native TUI was removed on 2026-10-05; `oceancode` starts Ocean TUI (drop `--tui ocean` / `OC_TUI=ocean`). The TUI's own slash commands, keys and settings are in Ocean TUI reference.

Binary

  1. Build the TUI: bash scripts/release/build-tui.sh (or cd ocean-tui && cargo build --release -p ocean-tui-bin --locked) → target/release/ocean-tui, the binary oceancode launches.
  2. A plain debug build lands in target/debug/ocean-tui and is never launched. To run a TUI build from elsewhere, set OC_TUI_BIN.

Discovery order: OC_TUI_BIN → ocean-tui beside oceancode (and beside the binary a symlinked oceancode resolves to) → ocean-tui on PATH. No other binary name is looked for.

oceancode sets $OC_TUI_HOME to <data>/oceancode/tui ($XDG_DATA_HOME, else ~/.local/share) — the directory a bare ocean-tui uses too — so the TUI shares no other tool's folder. Auto-update, remote fetch, feedback and voice are off. Every TUI variable: Environment.

Environment

Read by ocean-tui, not by the engine. Every TUI variable is OC_TUI_* (LC_OC_TUI_* over SSH); no other prefix is read.

VariableEffect
OC_TUI_HOMEThe TUI's state directory (config.toml, sessions, debug logs, the extracted ripgrep under bin/). oceancode sets it; unset → $XDG_DATA_HOME/oceancode/tui, else ~/.local/share/oceancode/tui.
OC_TUI_LOG_FILEWrite the TUI's debug log to exactly this path (honors RUST_LOG).
OC_TUI_DEBUG_LOGA path, or 1/true for <TUI home>/debug/tui-<pid>.txt: turns the debug log on.
OC_TUI_CONFIGInline JSON config overlay, merged above config.toml.
OC_TUI_CONFIG_PATHAn extra JSON or TOML config-overlay file (read by extension), merged above config.toml.
OC_TUI_MANAGED_CONFIG_FAIL_CLOSEDOverrides the requirements fail-closed setting (applies to requirements.toml only).
OC_TUI_SHELLShell the TUI spawns: an executable path (bash, zsh, …); on Windows pwsh, powershell or cmd.
OC_TUI_THEMEForce a theme name, or auto, without editing the config.
LC_OC_TUI_THEMESame as OC_TUI_THEME; the LC_ form survives SSH SendEnv LC_*.
OC_TUI_APPEARANCEdark or light: the terminal background auto themes assume.
LC_OC_TUI_APPEARANCESame as OC_TUI_APPEARANCE, SSH-forwardable.
OC_TUI_TERMINAL_THEMEFollow the terminal's own palette (on/off; a requirement pin wins).
OC_TUI_NERD_FONTSNerd Font glyphs in the git status (on/off).
OC_TUI_FORCE_LEGACY_CONSOLEWindows: ASCII-safe glyphs for the legacy console.
OC_TUI_SCREEN_MODEInternal: the screen mode a /fullscreen / /minimal relaunch hands to the new process (read and removed at startup).
OC_TUI_SCREEN_MODE_SWITCHexec forces the legacy re-exec switch between screen modes.
OC_TUI_SCROLL_SPEEDMouse-wheel scroll speed; applied on first load only (the settings modal persists it).
OC_TUI_SCROLL_MODEMouse-wheel scroll mode; first load only.
OC_TUI_SCROLL_LINESLines per wheel notch; first load only.
OC_TUI_INVERT_SCROLLInvert the wheel direction; first load only.
OC_TUI_SCROLL_CADENCE_MSThe shortest time between two repaints while scrolling (ms, 1 to 100). Unset, scrolling follows the display's refresh rate (8 to 16 ms, [ui.display_refresh]).
OC_TUI_MIN_DRAW_MSThe shortest time between two repaints caused by the engine (a streaming answer, tool output) or by the animation tick (ms, 1 to 100). The default is 33, at most 30 repaints a second; 16 gives the 60 a second of builds before 2026-11-13.
OC_TUI_INPUT_POLLSet to any non-empty value: the input reader checks the terminal every 20 ms, as it did before 2026-11-13, instead of waiting for input without a timer.
OC_TUI_DISPLAY_REFRESH_PROBE_ENABLEDProbe the display refresh rate at startup (on/off).
OC_TUI_DISPLAY_REFRESH_AUTO_CADENCEDerive the draw cadence from the probed refresh rate (on/off).
OC_TUI_SCROLL_DEBUGShow the scroll debug HUD.
OC_TUI_SCROLL_LOGLog scroll input events (unset or 0 = off).
OC_TUI_FPSShow the frames-per-second HUD.
OC_TUI_MEMTRACEMemory trace, on by default: footprint, allocator gauges and every memory purge (with its reason) go to memtrace/<start>-<pid>.jsonl in the TUI home; files older than 30 days are removed at start. 0/false/off disables.
OC_TUI_MEMTRACE_INTERVAL_SECSSeconds between memory-trace samples (default 30, at least 5).
OC_TUI_MEMTRACE_THRESHOLD_MBFootprint (MB) at which the trace records a threshold crossing (default 1024, then doubling).
OC_TUI_MOUSE_REPORTING_TOGGLEEnable the mouse-reporting toggle (on/off).
OC_TUI_SHOW_THINKING_BLOCKSShow model thinking blocks (on/off; overrides the setting).
OC_TUI_GROUP_TOOL_VERBSGroup consecutive tool calls by verb (on/off; overrides the setting).
OC_TUI_SHOW_EDIT_DETAILSShow each edit's diff inline — edit, write and apply_patch alike (on/off; overrides [ui] show_edit_details).
OC_TUI_SHOW_RUN_DETAILSFinished agent Runs show the command and first output lines (on/off; overrides [ui] show_run_details).
OC_TUI_COLLAPSED_EDIT_BLOCKSLegacy: start edit blocks collapsed (on/off); read only when show_edit_details is unset everywhere, as its inverse.
OC_TUI_CONTEXTUAL_HINTSContextual hints on/off (overrides [ui.contextual_hints]).
OC_TUI_TIPS_OVERRIDEDebug builds only: `
OC_TUI_SLASH_COMMAND_TAGSJSON map of tags shown beside slash commands in the / menu.
OC_TUI_DEFAULT_SELECTED_PERMISSIONWhich permission-card option the cursor starts on.
OC_TUI_ESC_DOUBLE_PRESS_MSWindow for the double-Esc gesture (ms).
OC_TUI_DOCKThe dock above the prompt on/off; on by default (0 brings back the Tasks pane at the top; a requirement pin wins, [features] dock in the TUI config comes after).
OC_TUI_DOCK_V2Same switch as OC_TUI_DOCK, read after it.
OC_TUI_AGENT_DASHBOARD0 turns /dashboard off.
OC_TUI_WORKSPACE_DASHBOARDUse the workspace (v2) dashboard layout instead of the persisted v1 layout.
OC_TUI_SESSION_PICKER_GROUPED1/0: group the session picker (overrides [cli] session_picker_grouped, default on).
OC_TUI_HUNK_TRACKERHunk-tracker mode (overrides [ui] hunk_tracker_mode).
OC_TUI_SUGGESTIONSShell-command ghost suggestions (off by default). They request ocean/suggest, which the Ocean engine does not serve, so nothing shows.
OC_TUI_SUGGESTIONS_AIAI variant of OC_TUI_SUGGESTIONS (same limitation).
OC_TUI_SUGGESTIONS_AI_MODELModel id for OC_TUI_SUGGESTIONS_AI.
OC_TUI_MCP_PUSH_SERVER_STATUSPush MCP server status updates into the UI (default on).
OC_TUI_ENVRC_TIMEOUT_SECSTimeout for evaluating a directory's .envrc (seconds; 0 disables).
OC_TUI_CONNECT_UI_TIMEOUT_SECSSeconds before startup shows the connect-failure report (6 s floor).
OC_TUI_PROMPT_ACK_TIMEOUT_SECSPrompt acknowledgement timeout (seconds).
OC_TUI_EXIT_TIMEOUT_SECSForce-exit this many seconds after a quit if teardown hangs (default 20; 0 disables).
OC_TUI_COPY_FILEBackup file every copy is also written to (default <TUI home>/last-copy.txt).
OC_TUI_OSC52_SINKEmit clipboard writes as OSC 52 for a wrapping terminal.
LC_OC_TUI_OSC52_SINKSame as OC_TUI_OSC52_SINK, SSH-forwardable.
OC_TUI_CLIPBOARD_NO_OSC52Never emit OSC 52 (for hosts that paint it as garbage).
OC_TUI_CLIPBOARD_NO_NATIVE_READmacOS: don't read the native pasteboard.
OC_TUI_CLIPBOARD_NO_DATA_CONTROLLinux: skip the Wayland data-control clipboard protocol.
OC_TUI_SQLITE_JOURNAL_MODESQLite journal mode for the TUI's local databases (the WAL kill switch).
OC_TUI_RESET_CHILD_OOMLinux, internal: set on child processes so they reset the inherited OOM score.
OC_TUI_EVENTSet for notification hook commands: the event name.
OC_TUI_MESSAGESet for notification hook commands: the message text.
OC_TUI_SESSION_IDSet for notification hook commands: the session id.
OC_TUI_BUNDLE_RG_PATHBuild time: embed this ripgrep binary instead of downloading the release tarball.
OC_TUI_RG_VERBuild-internal: embedded ripgrep version, set by ocean-tui-ripgrep/build.rs.
OC_TUI_RG_TARGETBuild-internal: embedded ripgrep target triple.
OC_TUI_RG_SHA256Build-internal: SHA-256 the extracted ripgrep is verified against.
OC_TUI_CHANGELOG_OFFLINETests: never fetch the changelog.
OC_TUI_MDM_NO_EXPAND_TESTTests: macOS managed-preferences layer.
OC_TUI_TEST_OPEN_URL_FILETests: write opened URLs to this file instead of launching a browser.
OC_TUI_TEST_FRAME_WRITE_DELAY_MSTests: delay each frame write (ms).
OC_TUI_TEST_HOLD_TEARDOWN_SECSTests: hold teardown to exercise the exit timeout.

What is wired to the Ocean engine

/, /mcps, /skills, /plugins, /hooks, /workflows, /model, and /effort use the TUI chrome and Ocean Services. MCP add/toggle, plugin enable/disable, hook reload, and tool permission cards go through ACP methods. The /workflows picker lists Off, Auto, the built-in workflows and your own YAML workflows over _ocean/mode, the method the work-mode picker reads; ocean/workflows/list still exists and still lists the .rhai scripts, but the TUI no longer reads it, so it lists them nowhere. Launching, pausing, resuming and stopping a run go through the workflow tool, not an ext request.

_ocean/mode. Besides {mode: <id>} (a way of working; a workflow id lands in the workflow setting) and {copy: <id>}, it takes {workflow: "auto" | "off" | "<id>" | ""}, the session's workflow setting ("" clears it), and the same with "default": true, which writes the user config's workflow key. {clear: true} clears both settings. Its reply adds workflow and default_workflow, and its current adds mode and workflow. A copy answers with the same report plus path (23 · Mode and workflow together).

Skills complete in the composer. Typing / and a prefix lists your enabled, user-invocable skills alongside the TUI's own commands — a plugin skill under Claude Code's plugin-qualified name (/superpowers:writing-plans, so /super finds every superpowers skill), a project or user skill under its bare name (/formatcode); the prefix narrows the list, Tab/Enter inserts /<skill> into the message box so you can keep typing, and sending dispatches it — the engine expands the skill body into the turn (a typed bare /writing-plans still runs the plugin skill too). The candidates come from ocean/skills/list (fetched at session start; the Ocean engine does not advertise skills as ACP commands), so a disabled skill is never offered. A Space toggle on the Skills tab of the capabilities picker updates the popup live, and the <available_skills> block and skill_* tools shrink on the next step (09 · Capabilities).

The capabilities picker. Each tab (/skills, /plugins, /hooks, /mcps, Marketplace) lists only its own kind. Workflows have no tab: /workflows opens the workflow picker in the prompt's place, where Enter turns Off, Auto or a workflow on for the session, d makes it the default for new sessions, and Build your own… and e start /workflow new and /workflow edit (22 · Workflow picker). On the Skills tab, Space toggles the skill under the cursor and the change sticks (it writes ~/.oceancode/skill-state.json); / opens a search that filters the rows by the skill's name, its slash id, its description and its author, case-insensitively, and a query that matches nothing reads No matches. a / d enable / disable every skill behind a confirm prompt. Each row shows its source — project, user or plugin: <name> — grouped by source.

Group and master toggles. On the Skills, Plugins, Hooks and MCP tabs Space also works above the single row; every change applies on the next step and costs one cache rewrite (09 · Capabilities):

Row / keyAction
Everything (first row) + SpaceMaster switch: off removes skills, MCP tools, hooks and plugin rules from the agent's context, built-in tools stay; asks first
All skills / All plugins / All MCP / All hooks (second row) + SpaceThe whole kind on or off; asks first
a / d (Skills tab)Same as All skills on / off
A Plugin: <name> header (Skills, MCP) or a hook source header + SpaceEvery row in the group; asks first above 10 rows; an all-off group reads [off]
A row + SpaceThat one skill, plugin, hook or MCP server

The picker's last row shows the live counts (skills 22/259 · plugins 2/21 · mcp 1/10 · hooks 8/8 · applies on the next step (one cache rewrite)), prefixed EVERYTHING OFF while the master switch is off. The Plugins tab also lists Claude Code's cached plugins under User (Claude). The Marketplace tab reads ~/.oceancode/marketplaces/** only when you open it (opening /skills or /plugins no longer touches the marketplace), and marketplace content never reaches the prompt or the tool list.

Pasted images

Paste an image from the clipboard (Ctrl+V / Cmd+V) or drag an image file onto the composer; it shows as [Image #1] in your text and goes to the model with the prompt ("what's wrong with this layout? [Image #1]"). Every route carries it — Anthropic, OpenAI chat and Responses (Groq, OpenRouter, …), Gemini. With several images, each is labelled [Image #N] in the request, so the model matches the name in your text to the right picture.

Limits: at most 20 images per prompt, 3.75 MiB per image once stored (about 5 MB once base64-encoded, the strictest limit of the routes), and 8000 px on either side (Anthropic refuses a larger image before the model runs; sips -Z 2576 <file> brings it under). The engine sends PNG, JPEG, GIF and WebP — the types every route accepts, decided by the image's bytes, not its declared type. The TUI re-encodes a TIFF (what a macOS screenshot usually is on the clipboard), BMP, ICO or GIF as PNG before it sends, so those paste and drag in like any other; PNG, JPEG and WebP go as they are. An image over the limits after that, a type the TUI cannot decode, or an http(s) source refuses the whole prompt with a message naming the image; nothing is dropped silently.

Dragging from another app. In Ocean AI Terminal a file dragged in from Photos or Finder becomes a chip the same way, and since desktop build 0.8.11 the drop also brings the terminal window to the front: macOS does not activate the window a drag lands on, so with an older build the keys you type next, Enter included, still go to the app the image came from until you click the terminal once.

Resizing. Images are resized so they never make a session fail (the same rules apply to images the read tool returns):

  • An image Claude would downscale is fitted to exactly the size Claude reads when it is pasted or read, so the provider never resamples it a second time and the pixels the model reasons about are the pixels in your session. Claude's current models read at most 2576 px on a side and 4784 visual tokens (one per 28×28 patch, about 3.75 megapixels); for nearly every screenshot the token budget decides — a 14" MacBook Pro Retina capture (3024×1964) is stored at 2380×1546, a 1920×1080 one goes as it is. The size is Anthropic's own reference resize; the resize is Lanczos3 with the aspect ratio kept; PNG stays PNG and JPEG stays JPEG, GIF and WebP become PNG. An image within both limits is sent byte for byte. For design review of fine detail (a 1 px border, a font size), paste a crop of the area rather than the whole screen: a crop under the limits reaches the model at full resolution.
  • When one request carries more than 20 images, Anthropic applies a stricter size limit to every image in it, so any image over 2000 px is sent as a 2000 px copy. The stored session is not changed.
  • If the provider still refuses an image for its size, the engine retries once with every image at or under the limit the provider named, and keeps that limit for the rest of the session.
  • Past 100 images or 24 MiB of image data in one request, the oldest images are replaced by a one-line note ([<name>, <W>x<H> omitted from this request: …; read the file again to see it]).

Text-only models. When the catalog says the current model reads no images (its models.dev entry lists input modalities without image), the text still goes and the image does not; a session note says so: Image #1 not sent: <model> doesn't accept images. A model the catalog cannot describe — an offline seed entry or one you declared under providers.*.models — gets the image. Switching to a text-only model after pasting drops the media from the request on the next turn — and an image a tool returns (read on a PNG) is replaced by a one-line note on such a model — so the provider does not answer 400.

The image is stored inline on the user row of oceancode.db ("files":[{"uri":"data:image/png;base64,…); a reopened session replays that row as text only, and the headless and server prompt bodies (07 · Headless and server) carry text only for now.

The dock: sub-agents above the prompt

Running sub-agents, background commands, monitors, loops and queued prompts live in one dock directly above the prompt, one section each (Agents, Tasks, Watchers, Queued). While a turn runs, its status rides the dock's first header instead of taking a row of its own:

▾ Agents 2  ⸬ Working 2m31s                                     1m20s ⇣12k [stop]
 ⸬ Find every caller of resolveWorkflowAccess — Running: rg -n …   1m15s silent · 4 tools · 38k tok · 2m13s
 ✓ Map the picker code paths                                       9 tools · 52k tok · 48s

A sub-agent row is the task's description, led by a badge only when the mission gave the sub-agent a persona or role (Researcher), then its live activity; the right column shows its tool calls, tokens and elapsed time, plus Ns silent once it has sent nothing for 10 s — amber from a minute, the one to open. The dock counts the agents, so the Ocean bar does not. Ctrl+G hides and shows the dock; a section folds on Enter or a click on its header, show N more opens a long one, ↗ opens a row and [stop] stops it. One blank row separates the transcript from what sits under it; nothing else is spaced.

The transcript keeps a record: Subagent running: "…" when a sub-agent starts and Subagent completed in 48s: "…" · 52k tok · 9 tools when it ends; the running line does not repeat the dock's live figures. OC_TUI_DOCK=0 (or [features] dock = false) brings back the Tasks pane at the top, the live figures on the transcript row and the agents N count in the bar.

A message to a sub-agent that had finished runs it again, and that run has its own dock row with live figures (0.8.8.50); [stop] on a row stops that sub-agent and nothing else. A sub-agent another Ocean Code process is running (the same session open in a second window) is refused by name rather than started a second time (12 · Session peers).

Under 90 columns the welcome screen has no logo box, so Ocean Code v… sits at the right end of the status bar (the bare v… when the row is short), never over the bar's text (0.8.8.37).

Under a work mode with an at-once limit (23), a sub-agent that must wait for a free slot gets a dock row of its own with a hollow glyph, waiting (4/4 running), which turns into its running row when a slot frees (or closes if the turn is stopped first). Model, the default, has no such limit, so this row never appears there.

Jobs that wake the agent

A background job the model starts (bash with background: true, monitor, loop, scheduler) is listed in the dock for as long as it runs, also while the session is idle. A monitor sits under Watchers, every other job under Tasks. The row names what the job is for and ends then the agent continues: when the job ends on its own, its result starts a new turn (08 · Bounding a long run). So a session that waits on a job reads as waiting, not as stuck (2026-11-17):

▾ Watchers 1
 ⸬ Monitor 0.8.8.112 is built — then the agent continues                                  14m05s [stop]

Enter or ↗ on the row opens the end of the job's output file (the last 64 KiB, read again every second while the job runs). [stop], or x on the row, stops that job and nothing else; a stopped job wakes no one. A job that ends while its output is open stays there, headed Task ended after …, until you close it. The list comes from the engine, and the last one wins, so a reopened session lists the jobs that still run. When the dock is hidden (Ctrl+G), the 1 monitor still running cue under the prompt brings it back with a click.

A command that runs

A bash command that has run for 10 seconds ends its transcript row with how long it has run, and with its time limit when the call gave one:

◆ Run Wait for 0.8.8.112 · 14m05s of 28m20s max

The count moves every second and goes when the command ends. In a narrow window the description is cut first, then the limit is left out; the count stays. Copying the row copies the command's text, never the count. A command that waits for your permission starts counting when you answer.

Row colours

Each transcript row starts with a ◆ whose colour says how it went; red means it failed, and nothing else is red (0.8.8.45):

ColourMeansRows
sky blue, pulsingrunninga bash command, a sub-agent, a background command, a workflow, any tool row you have expanded; also the dock's spinners, the dashboard and the tasks pane
greencompleteda sub-agent, background command or workflow that completed; a bash that exited 0
graydone, or nothing to flagevery other finished row, and a collapsed tool row (read, search, edit, …) while it runs
yellowstopped on purposea cancelled sub-agent or workflow, a killed background command, the Cancelling… status
redfaileda tool call that failed, a bash that exited non-zero, a failed sub-agent, background command or workflow; a group header (◈ Ran 2 subagents · 1 failed) with a failed member

A failed row keeps its reason on its collapsed line (◆ task task tool: run child session "…": … Provider request failed with HTTP 529); expand it for the full text. A collapsed row inside a group is drawn dimmer. Two reds are not about a row: [stop] while the pointer is on it, and the always-approve permission flag.

The work-mode picker (F4)

F4 or /mode opens the work-mode picker: who decides how agents work together — the model (Model, the default), Jev (Auto), or you (a way of working). The list sits on the left — the ways of working, then your own modes after ── custom ── — the highlighted mode's picture on the right, and under both, across the whole width, its description, when to use it and its cost; moving the cursor redraws them at once. Workflows are not in it: they are the session's workflow setting, set in /workflows, a picker laid out the same way, and the title row names that setting when it is not off (Workflow: Auto · /workflows to change). Enter uses the mode for this session, d makes it the current agent's default, e copies a built-in into .oceancode/modes/ to edit, Esc closes. /mode <id> and /mode default do the same without the picker. Every mode but Model shows its badge on the prompt's top border, at the left after the agent and the ultracode badge when that is on (delegate ≤4, race ×3, auto → goal · Jev 0.82), and under a workflow the task its run is on (spec ×3 · validate); Model shows none. F2 › Agent defaults holds a mode row per ring agent, and F2 › Sub-agents the three sub-agent limits (22). The modes, limits and requirements are on 23 · Work modes, the workflows on 24 · Workflows.

Watching a sub-agent

Open a sub-agent with a double-click or Enter on its dock row (↗), its transcript row or its Agent Dashboard row: the view fills with what the sub-agent does as it does it — its bash commands and their output, reads, greps, edits with their diff, and its text and thinking — with its own context bar. q or Esc closes it.

The engine streams a running sub-agent's activity live under the sub-agent's own session id, while the parent's turn runs and afterwards for a background sub-agent. A finished sub-agent whose view holds nothing yet — or whose view was freed after you closed it — is rebuilt from oceancode.db when you open it (ocean/session/replay). Sub-agents of a session you resumed, or of an earlier TUI run, do not open yet.

Goal mode (orchestrate: always)

Set orchestrate: "always" in the workflows section of oceancode.json and a plain prompt is no longer a single turn — it launches the built-in goal workflow, which plans the objective into verifiable deliverables, works in rounds with one resumed worker, and converges only when a panel of adversarial skeptics fails to refute completion (identical gaps two rounds running, or a spent budget, pause instead of looping). The TUI's Workflows dock shows the run advancing through its Plan → Work → Verify phases, with the sub-agents of each round beneath it. Since 2026-11-05 a goal run is drawn where every run is: the transcript's run block, the dock's row and the status row (Goal · round 2/10 · worker-1: Running bash…), with the goal chip and its overlay on top; a blocked goal's chip says why (Blocked: worker-0 failed (timeout)). The Claude-settings ultracode flag does not turn this on — only the explicit orchestrate opt-in does. Headless, the same goal run is oceancode goal "<objective>" (see 07-headless-and-server.md). Since work modes, orchestrate: "always" with no mode set is read as the Goal work mode (23).

What the TUI does not do

Login, billing, worktrees, /imagine and memory flush are unsupported (-32601).

The TUI has no Slack view: the Slack bridge runs inside every TUI window, and oceancode slack status is its surface (24 · Slack).

Connecting a provider is in the TUI: pick a gray /model row, or /connect <provider>. OpenCode-style auth methods:

  • API key — most providers (Google, Groq, Perplexity, …).
  • ChatGPT Plus/Pro — OpenAI, via OpenCode’s JSON deviceauth (auth.openai.com/codex/device), or paste an API key.
  • Claude Pro/Max — Anthropic PKCE (paste the browser code), or paste an API key.
  • GitHub Copilot — GitHub device flow (github.com/login/device).
  • claude-code — oceancode claude (Claude CLI login).
  • Bedrock / Vertex — environment/config, not a prompt.

Already-connected providers open a manage overlay: switch API key ↔ subscription, or d to disconnect (removes auth.json; env-backed providers stay connected until the env var is unset). Credentials go to the same auth.json as oceancode key / oceancode login.

A command that takes the terminal

An interactive shell started by a tool (zsh -lic '…', the -i makes it interactive) makes itself the owner of the terminal and does not give it back when it ends. Up to 0.8.8.59 the TUI then stopped reading the keyboard and the mouse and used a full CPU core until the window was killed. From 0.8.8.60 the TUI checks which process group owns its terminal and takes it back when it is neither the TUI nor the shell that started it (not while an external editor has it); the log says tty-guard: … took it back. The input reader makes this check right before every read, and a background check runs once a second (four times a second with OC_TUI_INPUT_POLL), so the window recovers within a second. A window still on an older build can be rescued from another terminal: kill -STOP <pid>, then fg in the frozen window. Ask the agent for zsh -lc instead of zsh -lic; a variable it needs from ~/.zshrc belongs in ~/.zprofile, which a login shell reads.

Speed and your terminal

Ocean TUI runs in your terminal, and your terminal draws it. Each frame sends only the cells that changed, wrapped in a synchronized update (DEC 2026) so the terminal shows the whole frame at once; an unchanged frame sends nothing. A streaming answer, tool output and the animations are repainted at most 30 times a second (OC_TUI_MIN_DRAW_MS; 16 gives 60 a second). Scrolling follows the display's refresh rate (8–16 ms a frame, [ui.display_refresh], OC_TUI_SCROLL_CADENCE_MS), and what you type is drawn at once. When nothing moves the TUI draws nothing and the process parks: the input reader waits for the terminal without a timer (OC_TUI_INPUT_POLL brings back its 20 ms poll), and an idle window wakes only while the peers chip turns or a lamp fades. Keystrokes and the mouse are handled before incoming text, so a slow terminal makes a stream arrive in bigger jumps but never blocks typing. OC_TUI_FPS=1 shows the frame rate. Nothing in the TUI uses the GPU; the terminal emulator does the drawing.

What the terminal adds: inline images in the transcript on Kitty, Ghostty and WezTerm (a placeholder elsewhere; the model receives the image either way, Pasted images); clickable paths and links (OSC 8) on iTerm2, Ghostty, Kitty, WezTerm, Alacritty, the VS Code family and Zed; the session's code and title in the tab on iTerm2 and WezTerm (Session peers); notifications over each terminal's own protocol (22 · notifications); true colour themes everywhere but Terminal.app, which gets the 16-colour fold. The Mac editing keys in the message box (⌘A select all, ⌘X, ⌘C, ⌘Z, ⌘⇧Z, ⌘← / ⌘→, ⌘⌫) reach the TUI only from terminals that hand ⌘ keys to the program: Ghostty, and the Ocean AI Terminal from desktop 0.8.17 (TERM_PROGRAM=OceanAITerminal), which also sends ⇧↵ as a new line.

Expired subscription

Ocean runs on the Claude subscription by consuming the active slot Claude Code keeps in ~/.claude/.credentials.json (claudeAiOauth); it never rotates that slot's refresh token. On macOS, once that file's token is within five minutes of expiry, Ocean also reads the Keychain item Claude Code refreshes itself into (Claude Code-credentials, read only) and uses whichever carries the later expiry, so a self-refresh by Claude Code no longer strands Ocean an hour later; no file still means no login. When the slot's access token has expired and carries no refresh token, a prompt cannot be sent, and the turn fails in the transcript with a terminal, actionable message — Claude subscription token has expired: Run oceancode login to reconnect your Claude account. — and no retry countdown or network banner (the failure is not a transport error and is never retried). Run oceancode login, complete the Claude Pro/Max browser flow, and send the prompt again. (Headless, oceancode run prints the same message to stderr and exits non-zero.)

The same holds when the slot expires mid-session: it was valid when the turn started, so the request reached Anthropic and the server rejected the now-dead token with an HTTP 401. On the subscription route that 401 (and a 403) is the same terminal run oceancode login failure — it is never retried — whereas a 401 on an API-key provider stays a generic error (its fix is a new key, not a re-login).

When the model refuses a message (the provider's content filter ends the response; Anthropic's stop_reason: "refusal"), the turn fails in the transcript as The model refused this message: Rephrase the message; if the refusal repeats, earlier messages in this conversation are tripping it, so start a new session. Whatever text arrived before the refusal stays above it. Nothing is retried and an open plan is not worked off into the same refusal: each attempt re-reads the whole conversation and is usually refused again. Some wording trips the classifier even in a legitimate question, and once such a message is in the conversation even a short follow-up (?) can be refused; rephrase, or /new. (Headless, oceancode run prints the same message to stderr and exits non-zero; an editor gets it as the prompt's error.)

Coming from the native TUI (removed 2026-10-05)

Ocean TUI renames some surfaces of the removed native TUI and has no ctrl+x leader — it uses direct chords. The equivalents:

Native TUI (removed 2026-10-05)Ocean TUINotes
/copy/toggle-mouse-reportingToggle terminal mouse capture so text selection/copy works.
/mcp/mcpsThe MCP-servers picker.
/models/modelThe model picker (also gates provider /connect).
/cockpitstatus bar + /contextNo unified cockpit panel; the status bar plus /context show the same figures.
ctrl+x leader chordsdirect chordsOcean TUI has no ctrl+x prefix. Use ctrl+p (command palette), ctrl+\ (Agent Dashboard), ctrl+t (todos pane), ctrl+m (multiline / model picker off the prompt).

Shift+Tab ring and permission modes

Shift+Tab cycles Build → Auto → Plan → Ask → Debug → Build. Build, Plan, Ask and Debug are the engine's agents (the curated ring in crates/ocean-acp/src/modes.rs); Auto is the one permission stop, Claude Code's "accept edits": the agent stays Build, the prompt border shows auto in yellow, and the engine's permission mode is acceptEdits — edits run without a card, bash and outside-directory asks still prompt (or go to Jev, see 13), and the question tool always asks. Cycling on from Auto drops back to ask before the switch to Plan. The stop is absent while always-approve is on, and when the auto feature is gated off ([auto_mode] enabled = false in the TUI config).

The same mode is reachable from /auto, /always-approve (ctrl+o; the engine's bypassPermissions, every card auto-answered by the TUI) and the permission_mode row of the settings modal. Each change is persisted to the TUI config and sent to the engine as ocean/yolo_mode_changed, so the engine's mode and the border flag agree (see 12 · Permissions and sandbox). A subagent's ask surfaces as its own card, labelled with the subagent.

The prompt's top border says at the left how the session runs, and at the right what it is working on:

╭─ Build · ultracode · orchestrate ≤8 ─────────────────────────── Session row colours ──╮

The agent is the bold label at the left, above the cursor (Build blue, Plan violet, Ask green, Debug orange). The mode badges follow it, bold in the model's colour: ultracode when that is on, then the work mode's badge. A border too narrow for them drops the badges, the last one first, and keeps the agent. The right side is the session's topic (below). The permission mode is on the bottom border (auto yellow, always-approve red). The Plan agent is plan mode, so it shows once, as Plan; plan approval and commenting L3 appear on the bottom border while a plan is under review.

Each agent can carry a default model and effort (agents.<id>.{model,effort} in oceancode.json, edited under F2 › Agent defaults): Shift+Tab to that agent puts the session on them, the effort clamped to the levels the model offers, and status-bar row 1 follows. Option+Tab (or F3, for terminals that don't send Option as Meta) steps the session's effort up through the current model's levels, wrapping to the lowest, and prints the same "Switched to …" line as /effort. That change lasts for the session: the next Shift+Tab loads the agent's own default again. An agent with no defaults keeps the session's model and effort.

A settings push reaches an open session live — a fleet-router Apply, an F2 edit, or a hand edit of oceancode.json or ~/.claude/settings.json. The TUI shows one toast naming what moved, for example Settings applied: sub-agents effort medium · build effort max, and status-bar row 1 shows the new values. The values it names are the main model and effort, ultracode, the sub-agent model and effort, FORCE, and each agent's model and effort. When the push changes the row of the session's current agent and the session still runs that row's old value, the session moves to the new one. A Mesh › Main change moves a session on the previous Main model unless its agent has a row of its own: the row wins (today that leaves Debug, which has no row). A model or effort you changed by hand in this session (/model, Option+Tab) is kept.

Question cards

When the agent asks with the question tool, a card replaces the composer: ↑/↓ walk the answers, Enter picks one (or starts typing on the last row, where you answer in your own words — that text reaches the model as written), ←/→ move between questions. An option can carry a preview (a snippet, a layout, a diff to compare), shown under the options while that option is focused, and the recommended option says why after its description. Nothing else in the agent's response runs while you are asked: a tool call it made after the question is answered "not run" and the agent makes it again once it has your answer, if it still needs to; calls made before the question finish before the card appears.

  • Ctrl+B back to chat leaves the question to give the agent more first — notes, pasted images, links. The turn stops, the answers you had picked land in the composer as My answers so far:, and the agent is told you stopped to add context; send your message and it thinks again and asks only what is still open.
  • Esc steps back (out of the text row, then clears a pick); X dismisses the card without answering; Ctrl+C cancels the turn and the open question with it. A second Ctrl+C right after it quits.

Resuming: the session tree

/resume (and the home screen's list) shows your main sessions only, most recently active first. A session that spawned sub-agents carries a fold glyph and says how many in the right column — › TUI fixes 3 sub · 5m ago — and the sub-sessions stay out of the way until you open it:

  • → (or e) on a parent row opens it: its sub-sessions are fetched the first time and drawn indented underneath; a sub-session that spawned its own folds the same way, as deep as the work went. On a row with nothing to open, → shows the detail card as before.
  • ← closes the detail card if it is open, then folds the sub-sessions away, then moves the selection up to the row's parent.
  • Typing searches titles on the engine, across main sessions and sub-sessions alike. A hit is drawn under its main session, with the rows between them dimmed when they did not match, so you can tell which run it belongs to. Clearing the search brings the folded list back.
  • A row badged open is already running in another TUI window on this machine; open it there instead of resuming it twice.
  • Enter resumes whichever row is selected, a sub-session included.

The engine names a session after the first prompt that says something — Hi, Yeah, Do it, Continue, [Image #1] and the like name it only until a real request arrives, so a list of greetings does not happen. A slash command names it by what you typed (/unlazy fix the dock), never by the skill or command text it expands to, and the engine's own prompts (the plan's Continue: work off …, a plan approval, a Stop hook's reason) never name it. A prompt a UserPromptSubmit hook blocks names nothing: it goes back to the front of the queue with its blocked-prompt card (10 · Hooks). /rename still wins over any automatic title.

A name stays. The name a session gets at its start is its name from then on (0.8.8.114). Before, the automatic title was refined over the first three prompts, and the topic below followed the work at every prompt, so a window you started for one thing could later carry another name. Now only /rename changes a named session. A name you give with /rename is yours: no automatic name replaces it, and every window shows it at once. /rename --auto gives the session back to the automatic name: its next real prompt names it once.

The session topic

The first prompt's line says how a request began, not what the work is, and most prompts begin alike. So a window also asks the model for a name of 2 to 5 words for what the session is about, for example Session row colours or Claude Code parity plan. That name is the session's title from then on: it is at the right of the prompt's top border, in the terminal tab after the session code, in the sessions list of every other window, in Messages, in oceancode status and in Slack.

  • When. Once, in the session's first turn, beside the turn: the name is there while the agent works. Later prompts make no topic call, so the name stays.
  • Not for. A session that already has a topic name, or a name you gave with /rename; a sub-agent.
  • Cost. One small request per session on the session's model at its lowest effort, without tools. It reads at most the last 12 messages, each cut short. The first three calls measured cost $0.004 to $0.007 each at list price on the largest model. Each call is recorded as a child session named Topic.
  • Where. Only in the TUI. oceancode run, goal, workflow, serve and acp make no such call.
  • Off. OC_SESSION_TOPIC=0 in the window's environment: the border's right side stays empty and the title is the first prompt's line, as before 0.8.8.87.

Search counter and tideline tiers

The top-right status row shows a search N · 0.3s chip once the session has run a grep or glob tool call: N is the number of calls, the time is the last call's latency (green ≤ 1 s, yellow ≤ 5 s, orange above). Click it for the breakdown — calls by tool, last / average / total latency, bytes and files scanned, and how many recursive grep -r / find the model ran through bash (and how many of those were rewritten to rg). The figures are folded from each tool result's metadata (elapsed_ms, files, bytes, search_redirect) in oceancode.db, so they survive a restart; nothing is counted in memory.

Beside it, once the first step has finished, a ttft 0.8s · api 1.9s chip shows the last step's time to first token and the provider's round trip; click it for the session's p50 and p95, and /usage lists the same three rows (time to first token, round trip, tool wall time). The figures are folded from the stored steps, so they survive a restart too.

The Ocean context row (ctx … N% full · tideline …) is tiered against the tideline limit: green all the way up to it, orange at or over it, red from 20 % over it (480k on a 400k line); the gauge, the percentage and the tideline clause share the tone. With the ledger off the row is tiered against the context window: green under 80 % of it, yellow from 80 %, orange when it is full. tideline ×12 @30% … carries the number of turns past the tideline (/tideline prints the same figure); no ×N while it is zero. Over the limit the clause reads tideline reached (+45k over 300k); tideline stuck (+45k over 300k, nothing closed) is the engine's own report that no block is closed to cut; it clears at the next step unless the part of the window that is never cut is itself over the line, and then it stays until the line is raised (/tideline prints the open block, the closed blocks and the line it reads).

The context row ends with the session's token totals, … · ↑2.1M │ ↓48k: ↑ is what was sent to the model, ↓ what came back, refreshed after every step, with a faint │ between them (0.8.8.60). As the row narrows they outlive the N% left (x/y) figures but not the full tideline clause. The two arrows are lamps for the traffic with the model, for this session and every running sub-agent, each in its own colour (0.8.8.61):

LampGlowsMeans
↑bluea request is out and nothing has come back yet (sending)
↓greenan answer streams in: thinking, text or a tool call (receiving)
neithergreya tool runs, or the session rests

A lamp never blinks: it fades in and out in a quarter of a second and, while it stays on, breathes slowly (dims and comes back every two seconds), so a long stream reads as alive without flashing. One agent sends and receives in turn, so only one arrow glows; both glow at once only while two agents work, one waiting and one receiving. On a terminal without RGB colour the lamp is plainly lit or grey. While a turn runs before the first totals arrive the arrows read ↑0 │ ↓0. (0.8.8.58–0.8.8.60 flashed ↑ per request and blinked ↓ per message.)

The bash tool rewrites a plain recursive grep -r … to the bundled ripgrep (POSIX shells; every flag must have an rg equivalent, patterns are literal-safe) and prepends [oceancode] ran as: rg … to the result; any other recursive grep or a find … -name runs as typed under a one-line hint naming the grep / glob tools. A leading cd <dir> &&/; prefix, a trailing 2>/dev/null, | grep -v … / | head followers, and BRE \| alternation are carried or translated verbatim, so the common slow pipelines still rewrite. The ripgrep directory leads the child PATH, so rg is available in bash on every OS where a binary resolves (OC_RG_BIN overrides; see 02).

Session peers

Every session has a code, the last four characters of its id: the third row under the prompt, the window's last row, starts with it (#2oca; in a window of 16 rows or fewer it is on the right of row 1 of the Ocean bar instead), and the terminal tab title starts with it (#2oca Fix login; also the ocean_session user variable). oceancode status 2oca, /status 2oca and the sessions tool find a session by it, in any case.

That third row lists every Ocean Code session on this Mac with what it is doing, this window first:

#2oca idle · #HERA needs you · #MpJ9 writing  · #zAgb thinking · #RxVC idle · #wmGe empty

Every session reads by the same words and colours, this window included; its code is the blue, bold one (the colour of a link in the text), the other codes are grey.

WordColourMeans
emptygreya window nobody has typed into yet; it can take a request from another session
idlegreyat rest
thinkinggreenin a turn: the model is generating
readinggreenin a turn: it reads or searches files or the web
writinggreenin a turn: it changes files
runninggreenin a turn: it runs a command (a build, tests, the shell)
busygreenin a turn: anything else (a sub-agent, a workflow, an MCP tool)
needs youyellow, boldit waits for your answer: a permission card or a question
blockedred, boldit wants a file another session holds

The word of a session in a turn follows the tool it runs, and can be up to two seconds behind. With sub-agents it is what the most recent one does. A window still running a build older than this one keeps the last tool's word while its model generates, until it is relaunched.

After this window the sessions that need a look come first: needs you, blocked, the ones in a turn, idle, empty. A session keeps its place while it works, and its word keeps its width, so the row does not jump. When the row has no room for all of them it ends in … +3 (three more); the ones left out are the last in that order. Click anywhere on the list, the … included, to open the sessions list described below.

In a window of 16 rows or fewer there is no third row, and row 1 of the Ocean bar shows a chip on its right that counts the other sessions instead (OC is Ocean Code; no chip when there are no others). It has two faces, and while the others have something to say it turns between them every four seconds, the words fading out and the next ones in, like a departures board (0.8.8.61): this window's own state, and what the others do.

This windowThe othersChip
idleidle⇄1 OC idle (one face)
in a turnidle⇄1 OC busy (one face)
idleone of them in a turn⇄1 OC idle ↔ ⇄1 OC 1 busy
in a turnthree in a turn⇄3 OC busy ↔ ⇄3 OC 3 busy
idleone waits for your answer⇄2 OC idle ↔ ⇄2 OC 1 needs you

This window's words never carry a number (idle, busy, blocked); the others' always do (1 busy, 1 needs you, 2 need you). A change shows its news first: when one of the others starts or finishes, the chip turns to their face; when this window starts or ends a turn, to its own. The glyph and ⇄N OC wear the chip's colour, the most urgent state shown, on both faces, by the row's colours; this window's words wear its own (grey idle, green busy):

ChipColourMeans
OC idlegreyevery session is at rest
OC busy, OC 1 busygreen, the tideline'sthis window or another session is in a turn
OC 1 needs youyellow, boldanother session waits for your answer
OC blockedred, boldthis session is blocked by another one's claim (one face)

The chip keeps its place while it turns (its words are padded to the longer face). An idle window wakes four times a second while the chip turns, twelve times a second for the fade itself, and parks when nobody else works.

When row 1 is tight it shortens words before it drops anything, in this order: the separators tighten (|, the code and the chip joined by a space); sub-agents reads sub; the word effort goes while its value stays (Opus 5.5 xhigh · sub Opus 5.5 high); and last the chip's words (⇄2 OC, its colour still says it; it no longer turns). Only a narrower row drops the sub-agent model. This window's own session is not counted, so two TUI windows each read ⇄1. A session counts from its first prompt (its row is written when a turn starts). Every engine on the session line takes part (12 · Session peers); a window started on a build from before the line (2026-11-18) sees only other such windows and stays invisible to the new ones until it is relaunched. Click the row, or the chip, to open Messages on its Sessions tab (Messages). /peers opens the same tab; /peers take <path | name:label> gives a claim another session holds to this session. The engine pushes the list (ocean/peers/changed) as soon as the line reports a change, and only when the list changed. How claims work: 12 · Session peers.

Messages

Everything between sessions is in one window, Messages. Three things open it:

  • [Messages] at the left of the session header, on its Inbox tab. [Messages 2] counts the messages waiting for this window, the number in the warning colour.
  • A click on the session row or the ⇄N chip under the Ocean bar, on its Sessions tab.
  • /messages, on its Inbox tab.

The entry shows once the engine has sent the list of sessions; with session peers off, or in a sub-agent's view, it is not there.

┌─ Messages ───────────────────────────────────────────────────── [✗] ─┐
│  Inbox 1  Sessions 2                                                 │
│──────────────────────────────────────────────────────────────────────│
│  ▸ r12  from #f2k1 "Schema work" · waiting 2m · db/schema.sql        │
│         users.email has no unique index (db/schema.sql:41)           │
│    r11  to #f2k1 "Schema work" · accepted 14m                        │
│         please check the schema                                      │
│                                                                      │
│  See sessions on · Messages on · Other machines on                   │
│  Enter accept · d decline · w withdraw · Tab sessions · s settings   │
└──────────────────────────────────────────────────────────────────────┘
  • Inbox lists every message between this window's sessions and the others: the ones waiting for this window first, then newest first, each with who sent it, to whom, its state, its age and its text. A message another session's agent sent (its ask_session) and one its user typed read alike; the one a user typed reads from #f2k1 "Schema work" (its user). Enter (or a) accepts the selected message and d declines it, when it waits for this window. w takes back one this window accepted while it still waits in the queue. A message this window sent that is still open reads delivered once the other window has it (to #f2k1 "Schema work" · delivered 1m, the time since it got there), and waiting until then.
  • Sessions lists every Ocean Code session: this window first, then the others on this Mac, then sessions on other machines that share the project's hub (12 · Across machines). A row has the session's code, name, state, how long it has been open, the file it writes and, last, its folder, as in #q7rt Docs idle 12m · open 9m · writing user-guide/19-tui.md · /repo/docs. A long folder is cut at the window's edge. A session of an engine older than 0.8.8.114 shows no open time. Enter on a session closes the window and puts /message #f2k1 in the prompt: write the message and press Enter. This window (this window) is dimmed and skipped by the selection. So is another machine's session (other machine), unless the project carries messages across machines and that session takes them (12 · Across machines, "messages": true): then it is picked like one on this Mac.
  • The status line under the list names the three switches, as in See sessions on · Messages on · Other machines on. s opens F2 at Messaging, the one place they are changed (22 · Messaging; what each one turns off: 12 · Switching it off).

Tab, Shift+Tab, the left and right arrows or a click on a tab switch the tabs. A click selects a row; Esc, [✗] or a click outside closes. The window follows new messages and sessions while it is open.

Sending. /message #f2k1 <text> sends a message without opening the window (/messages and /msg are the same command); typing /message pops up the sessions to pick from, as the Sessions tab lists them. The toast says Sent r12 to #f2k1. A message is refused, with the reason, when it names:

  • this session;
  • a session that is gone;
  • a session on another machine, unless the project carries messages across machines and that session takes them; when the project's database does not answer, the toast says Not sent: and why;
  • a window that takes no messages (its peers.requests is off, or it is not a TUI window).

It is also refused while this window's own messages are off, and the limits of the agent's requests apply.

Receiving. A message prints nothing into the conversation. The receiving window toasts Message r12 from #2oca · /messages and counts it on [Messages]. Accepting queues it as this session's next prompt, like a typed one, so it runs after the current turn; declining ends it. A message waiting for an empty window shows in every empty window open in that project, and the first to accept it takes it; an empty window still on its home screen opens its session, so the toast and [Messages 1] show. Only the owner route names a file, shown inside this session's folder. The sending window toasts each change: r12 delivered to #f2k1 once the other window has it (one toast; when that happens while Sent r12 to #f2k1 is still showing, which is the usual case, that toast reads Sent r12 to #f2k1 · delivered instead), then r12 accepted in #f2k1, then r12 done in #f2k1 when the turn that ran it finishes, r12 stopped in #f2k1 when that turn was cancelled or failed, or declined / expired. Deleting an accepted message's queued prompt (the queue's delete key, its [cancel], the edit dialog's delete, or a dashboard stop that drops the queue) withdraws it: it reads declined, toasted Withdrew r12 here. So does a UserPromptSubmit hook blocking that prompt. Editing the prompt before it runs keeps the message: its turn still marks it.

/status prints the board of every Ocean Code session on this machine, sessions that wait for you first: each session's code (#2oca, the last four characters of its id), its state (waiting for you, blocked, stuck?, working, idle, empty, done, crashed, closed), its plan progress, the row it is on and the next one, its helpers, the files it holds and a rough estimate. /status all adds closed sessions; /status <code | words> finds one. oceancode status and the agent's sessions tool print the same board (21 · oceancode status). A window you opened but never typed into reads empty. A session is open in one window at a time: opening it (/resume, --resume) while another Ocean Code window has it open is refused, naming that window's pid, and works once that window closes or dies.

Where it left off. Opening a session that has open plan rows, tool calls of its last turn that were still running when its window closed or crashed, or a last turn that stopped before it finished (Esc, a provider failure, a quit between steps), prints a resume card under the replayed transcript:

Where #2oca left off — "AI consulting v3"
Last active 14:05 (12m ago) · plan 3/9 · ended: crashed
  now:  Task 16: round-2 re-review running
  next: Task 16 fix round 2
  interrupted: bash `bash x3-steps.sh` (14:03)
  stopped: the last turn did not finish (14:04)
Type /continue to carry on from here.

/continue sends the prompt that carries on: the plan's next open rows and, when something was interrupted, the list of interrupted calls to check before repeating them (an interrupted sub-agent is named by its description). A last turn that stopped before it finished adds a stopped: line, with the provider's error when it failed, and the prompt asks the agent to check what that turn already did before repeating it. It is queued like a typed prompt. A read-only agent (plan, ask) gets the plain Continue where you left off., since the engine never works off its plan. A replayed tool call that was cut off reads Tool execution was interrupted before it completed., never as completed (a call the model was still writing when you pressed Esc never ran and shows as it did then). A finished session (every row done, nothing interrupted, its last turn ended cleanly) shows no card, and /continue says there is nothing to continue. While a turn of the session runs there is no card, and /continue says This session is still working. Press Esc to stop it, then /continue.; while it waits on background sub-agents still working, /continue sends nothing and says Waiting on 2 sub-agents; the session carries on when they report. ended: says whether the window that had it was closed or crashed. After /pause, /continue lets the paused agents go on instead (Pause before you go offline).

Pause before you go offline

/pause holds every agent of this window, the session's own turn and every sub-agent, foreground or background, before its next call to the model. Nothing is cancelled: a reply already streaming finishes, a running tool call finishes and its result is kept, and a prompt you send while paused waits its turn. The status bar shows Pausing… while a reply still streams, then Paused, and the transcript says Paused at 14:05. Nothing calls the model until /continue. From that line on it is safe to close the lid or lose the network. A second /pause says Already paused. Type /continue to carry on.

/continue first checks the provider answers. Still offline, it stays paused and says why: Still offline: <reason>. Still paused; type /continue again once you're connected. Online, the chip goes, the transcript says Continued after 1h 02m., and every agent goes on from the step it waited at. Time spent paused does not count against the run's wall clock (/limits time) or a workflow agent's timeout. While paused, the cache keep-alive, /btw, /compact and the ledger's merge calls send nothing (/btw and /compact say Ocean Code is paused. Type /continue first.).

The pause lives in the running engine: quitting Ocean Code ends it, and the next window starts unpaused (the resume card then offers /continue for what was left). A turn that loses the network without /pause fails after five minutes without data from the provider, so it never hangs; /continue then carries it on.

Ocean session commands

These act on the Ocean engine over _ocean/* / ocean/* ext methods (Ocean backend only):

CommandWhat it does
/tidelineBare shows the ledger state; /tideline now cuts the ledger; <n>%, <tokens>, or default set the tideline (the floor and the presets were removed — a second number or a preset word is refused with the usage line). The old /shelve still works as a hidden alias.
/retentionBare shows how long idle sessions are kept and what the next sweep would delete (retention 7 days · 12 sessions pending · first sweep after <date> (grace), or … · last sweep 5m ago, 340 swept); <days> sets retention.days in the global config and re-arms the sweep at once; off is 0 (keep everything). An out-of-range number is refused with the engine's message. While sessions wait out the 24-hour grace window the context row shows retention N pending and one notice is toasted. See 18 · Operations.
/budgetBare shows the spend cap; $5 (or 5) caps USD, off clears it, subscription switches to list-price mode.
/limitsBare shows the per-turn bounds; steps <n> caps steps, time <90m|1h30m> bounds wall-clock.
/subagentBare reports the effective sub-agent model + source; <provider/model> pins one, default / off / clear removes the override.
/modeBare opens the work-mode picker (as F4); <id> sets this session's work mode; a workflow id (/mode spec) turns that workflow on and leaves the mode as it is; default clears both, so the agent's or the config's settings apply again. Answered with a toast, Mode: <label>. See 23.
/plan add|done|cancel|edit|removeEdit the live todo table (1-based rows); bare /plan still enters plan mode.
/redoRe-apply the turn a /undo (/rewind) reverted, and the files it put back.
/shareShare this session via a public URL (Ocean backend).
/unshareRevoke the current session's share link.
/notifyToggle desktop notifications; /notify on|off sets it explicitly.
/peersBare opens Messages on its Sessions tab, the sessions on this machine (the same as a click on the ⇄N OC <state> chip); take <path | name:label> gives a claim another session holds to this session. Messages are answered in Messages; the switches are in F2 › Messaging. See Session peers.
/messagesOpens Messages: the inbox of messages between sessions and the list of sessions; /message #f2k1 <text> sends one (/msg too). See Messages.
/statusThe board of every Ocean Code session on this machine; all adds closed sessions, <code | words> finds one. See Session peers.
/slackSlack on or off for every window on this Mac; /slack on|off sets it. See 24 · Slack.
/continueAfter /pause: check the provider answers, then let every agent go on (_ocean/continue). Otherwise carry on where the session left off: queues a prompt built from its open plan rows, the tool calls a stopped window cut off and a last turn that stopped before it finished. See Pause before you go offline and Session peers.
/pauseHold every agent and sub-agent of this window before its next model call (_ocean/pause); the status bar shows Paused until /continue. See Pause before you go offline.