Use
Ocean TUI
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
- Build the TUI:
bash scripts/release/build-tui.sh(orcd ocean-tui && cargo build --release -p ocean-tui-bin --locked) →target/release/ocean-tui, the binaryoceancodelaunches. - A plain debug build lands in
target/debug/ocean-tuiand is never launched. To run a TUI build from elsewhere, setOC_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.
| Variable | Effect |
|---|---|
OC_TUI_HOME | The 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_FILE | Write the TUI's debug log to exactly this path (honors RUST_LOG). |
OC_TUI_DEBUG_LOG | A path, or 1/true for <TUI home>/debug/tui-<pid>.txt: turns the debug log on. |
OC_TUI_CONFIG | Inline JSON config overlay, merged above config.toml. |
OC_TUI_CONFIG_PATH | An extra JSON or TOML config-overlay file (read by extension), merged above config.toml. |
OC_TUI_MANAGED_CONFIG_FAIL_CLOSED | Overrides the requirements fail-closed setting (applies to requirements.toml only). |
OC_TUI_SHELL | Shell the TUI spawns: an executable path (bash, zsh, …); on Windows pwsh, powershell or cmd. |
OC_TUI_THEME | Force a theme name, or auto, without editing the config. |
LC_OC_TUI_THEME | Same as OC_TUI_THEME; the LC_ form survives SSH SendEnv LC_*. |
OC_TUI_APPEARANCE | dark or light: the terminal background auto themes assume. |
LC_OC_TUI_APPEARANCE | Same as OC_TUI_APPEARANCE, SSH-forwardable. |
OC_TUI_TERMINAL_THEME | Follow the terminal's own palette (on/off; a requirement pin wins). |
OC_TUI_NERD_FONTS | Nerd Font glyphs in the git status (on/off). |
OC_TUI_FORCE_LEGACY_CONSOLE | Windows: ASCII-safe glyphs for the legacy console. |
OC_TUI_SCREEN_MODE | Internal: the screen mode a /fullscreen / /minimal relaunch hands to the new process (read and removed at startup). |
OC_TUI_SCREEN_MODE_SWITCH | exec forces the legacy re-exec switch between screen modes. |
OC_TUI_SCROLL_SPEED | Mouse-wheel scroll speed; applied on first load only (the settings modal persists it). |
OC_TUI_SCROLL_MODE | Mouse-wheel scroll mode; first load only. |
OC_TUI_SCROLL_LINES | Lines per wheel notch; first load only. |
OC_TUI_INVERT_SCROLL | Invert the wheel direction; first load only. |
OC_TUI_SCROLL_CADENCE_MS | The 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_MS | The 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_POLL | Set 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_ENABLED | Probe the display refresh rate at startup (on/off). |
OC_TUI_DISPLAY_REFRESH_AUTO_CADENCE | Derive the draw cadence from the probed refresh rate (on/off). |
OC_TUI_SCROLL_DEBUG | Show the scroll debug HUD. |
OC_TUI_SCROLL_LOG | Log scroll input events (unset or 0 = off). |
OC_TUI_FPS | Show the frames-per-second HUD. |
OC_TUI_MEMTRACE | Memory 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_SECS | Seconds between memory-trace samples (default 30, at least 5). |
OC_TUI_MEMTRACE_THRESHOLD_MB | Footprint (MB) at which the trace records a threshold crossing (default 1024, then doubling). |
OC_TUI_MOUSE_REPORTING_TOGGLE | Enable the mouse-reporting toggle (on/off). |
OC_TUI_SHOW_THINKING_BLOCKS | Show model thinking blocks (on/off; overrides the setting). |
OC_TUI_GROUP_TOOL_VERBS | Group consecutive tool calls by verb (on/off; overrides the setting). |
OC_TUI_SHOW_EDIT_DETAILS | Show each edit's diff inline — edit, write and apply_patch alike (on/off; overrides [ui] show_edit_details). |
OC_TUI_SHOW_RUN_DETAILS | Finished agent Runs show the command and first output lines (on/off; overrides [ui] show_run_details). |
OC_TUI_COLLAPSED_EDIT_BLOCKS | Legacy: start edit blocks collapsed (on/off); read only when show_edit_details is unset everywhere, as its inverse. |
OC_TUI_CONTEXTUAL_HINTS | Contextual hints on/off (overrides [ui.contextual_hints]). |
OC_TUI_TIPS_OVERRIDE | Debug builds only: ` |
OC_TUI_SLASH_COMMAND_TAGS | JSON map of tags shown beside slash commands in the / menu. |
OC_TUI_DEFAULT_SELECTED_PERMISSION | Which permission-card option the cursor starts on. |
OC_TUI_ESC_DOUBLE_PRESS_MS | Window for the double-Esc gesture (ms). |
OC_TUI_DOCK | The 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_V2 | Same switch as OC_TUI_DOCK, read after it. |
OC_TUI_AGENT_DASHBOARD | 0 turns /dashboard off. |
OC_TUI_WORKSPACE_DASHBOARD | Use the workspace (v2) dashboard layout instead of the persisted v1 layout. |
OC_TUI_SESSION_PICKER_GROUPED | 1/0: group the session picker (overrides [cli] session_picker_grouped, default on). |
OC_TUI_HUNK_TRACKER | Hunk-tracker mode (overrides [ui] hunk_tracker_mode). |
OC_TUI_SUGGESTIONS | Shell-command ghost suggestions (off by default). They request ocean/suggest, which the Ocean engine does not serve, so nothing shows. |
OC_TUI_SUGGESTIONS_AI | AI variant of OC_TUI_SUGGESTIONS (same limitation). |
OC_TUI_SUGGESTIONS_AI_MODEL | Model id for OC_TUI_SUGGESTIONS_AI. |
OC_TUI_MCP_PUSH_SERVER_STATUS | Push MCP server status updates into the UI (default on). |
OC_TUI_ENVRC_TIMEOUT_SECS | Timeout for evaluating a directory's .envrc (seconds; 0 disables). |
OC_TUI_CONNECT_UI_TIMEOUT_SECS | Seconds before startup shows the connect-failure report (6 s floor). |
OC_TUI_PROMPT_ACK_TIMEOUT_SECS | Prompt acknowledgement timeout (seconds). |
OC_TUI_EXIT_TIMEOUT_SECS | Force-exit this many seconds after a quit if teardown hangs (default 20; 0 disables). |
OC_TUI_COPY_FILE | Backup file every copy is also written to (default <TUI home>/last-copy.txt). |
OC_TUI_OSC52_SINK | Emit clipboard writes as OSC 52 for a wrapping terminal. |
LC_OC_TUI_OSC52_SINK | Same as OC_TUI_OSC52_SINK, SSH-forwardable. |
OC_TUI_CLIPBOARD_NO_OSC52 | Never emit OSC 52 (for hosts that paint it as garbage). |
OC_TUI_CLIPBOARD_NO_NATIVE_READ | macOS: don't read the native pasteboard. |
OC_TUI_CLIPBOARD_NO_DATA_CONTROL | Linux: skip the Wayland data-control clipboard protocol. |
OC_TUI_SQLITE_JOURNAL_MODE | SQLite journal mode for the TUI's local databases (the WAL kill switch). |
OC_TUI_RESET_CHILD_OOM | Linux, internal: set on child processes so they reset the inherited OOM score. |
OC_TUI_EVENT | Set for notification hook commands: the event name. |
OC_TUI_MESSAGE | Set for notification hook commands: the message text. |
OC_TUI_SESSION_ID | Set for notification hook commands: the session id. |
OC_TUI_BUNDLE_RG_PATH | Build time: embed this ripgrep binary instead of downloading the release tarball. |
OC_TUI_RG_VER | Build-internal: embedded ripgrep version, set by ocean-tui-ripgrep/build.rs. |
OC_TUI_RG_TARGET | Build-internal: embedded ripgrep target triple. |
OC_TUI_RG_SHA256 | Build-internal: SHA-256 the extracted ripgrep is verified against. |
OC_TUI_CHANGELOG_OFFLINE | Tests: never fetch the changelog. |
OC_TUI_MDM_NO_EXPAND_TEST | Tests: macOS managed-preferences layer. |
OC_TUI_TEST_OPEN_URL_FILE | Tests: write opened URLs to this file instead of launching a browser. |
OC_TUI_TEST_FRAME_WRITE_DELAY_MS | Tests: delay each frame write (ms). |
OC_TUI_TEST_HOLD_TEARDOWN_SECS | Tests: 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 / key | Action |
|---|---|
Everything (first row) + Space | Master 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) + Space | The 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 + Space | Every row in the group; asks first above 10 rows; an all-off group reads [off] |
A row + Space | That 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 · 48sA 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 maxThe 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):
| Colour | Means | Rows |
|---|---|---|
| sky blue, pulsing | running | a 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 |
| green | completed | a sub-agent, background command or workflow that completed; a bash that exited 0 |
| gray | done, or nothing to flag | every other finished row, and a collapsed tool row (read, search, edit, …) while it runs |
| yellow | stopped on purpose | a cancelled sub-agent or workflow, a killed background command, the Cancelling… status |
| red | failed | a 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 TUI | Notes |
|---|---|---|
/copy | /toggle-mouse-reporting | Toggle terminal mouse capture so text selection/copy works. |
/mcp | /mcps | The MCP-servers picker. |
/models | /model | The model picker (also gates provider /connect). |
/cockpit | status bar + /context | No unified cockpit panel; the status bar plus /context show the same figures. |
ctrl+x leader chords | direct chords | Ocean 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+Bback 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 asMy 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.Escsteps back (out of the text row, then clears a pick);Xdismisses the card without answering;Ctrl+Ccancels the turn and the open question with it. A secondCtrl+Cright 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:
→(ore) 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
openis already running in another TUI window on this machine; open it there instead of resuming it twice. Enterresumes 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,serveandacpmake no such call. - Off.
OC_SESSION_TOPIC=0in 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):
| Lamp | Glows | Means |
|---|---|---|
↑ | blue | a request is out and nothing has come back yet (sending) |
↓ | green | an answer streams in: thinking, text or a tool call (receiving) |
| neither | grey | a 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 emptyEvery 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.
| Word | Colour | Means |
|---|---|---|
empty | grey | a window nobody has typed into yet; it can take a request from another session |
idle | grey | at rest |
thinking | green | in a turn: the model is generating |
reading | green | in a turn: it reads or searches files or the web |
writing | green | in a turn: it changes files |
running | green | in a turn: it runs a command (a build, tests, the shell) |
busy | green | in a turn: anything else (a sub-agent, a workflow, an MCP tool) |
needs you | yellow, bold | it waits for your answer: a permission card or a question |
blocked | red, bold | it 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 window | The others | Chip |
|---|---|---|
| idle | idle | ⇄1 OC idle (one face) |
| in a turn | idle | ⇄1 OC busy (one face) |
| idle | one of them in a turn | ⇄1 OC idle ↔ ⇄1 OC 1 busy |
| in a turn | three in a turn | ⇄3 OC busy ↔ ⇄3 OC 3 busy |
| idle | one 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):
| Chip | Colour | Means |
|---|---|---|
OC idle | grey | every session is at rest |
OC busy, OC 1 busy | green, the tideline's | this window or another session is in a turn |
OC 1 needs you | yellow, bold | another session waits for your answer |
OC blocked | red, bold | this 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
⇄Nchip 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 readsfrom #f2k1 "Schema work" (its user). Enter (ora) accepts the selected message andddeclines it, when it waits for this window.wtakes back one this window accepted while it still waits in the queue. A message this window sent that is still open readsdeliveredonce the other window has it (to #f2k1 "Schema work" · delivered 1m, the time since it got there), andwaitinguntil 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 #f2k1in 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.sopens 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.requestsis 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):
| Command | What it does |
|---|---|
/tideline | Bare 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. |
/retention | Bare 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. |
/budget | Bare shows the spend cap; $5 (or 5) caps USD, off clears it, subscription switches to list-price mode. |
/limits | Bare shows the per-turn bounds; steps <n> caps steps, time <90m|1h30m> bounds wall-clock. |
/subagent | Bare reports the effective sub-agent model + source; <provider/model> pins one, default / off / clear removes the override. |
/mode | Bare 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|remove | Edit the live todo table (1-based rows); bare /plan still enters plan mode. |
/redo | Re-apply the turn a /undo (/rewind) reverted, and the files it put back. |
/share | Share this session via a public URL (Ocean backend). |
/unshare | Revoke the current session's share link. |
/notify | Toggle desktop notifications; /notify on|off sets it explicitly. |
/peers | Bare 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. |
/messages | Opens Messages: the inbox of messages between sessions and the list of sessions; /message #f2k1 <text> sends one (/msg too). See Messages. |
/status | The board of every Ocean Code session on this machine; all adds closed sessions, <code | words> finds one. See Session peers. |
/slack | Slack on or off for every window on this Mac; /slack on|off sets it. See 24 · Slack. |
/continue | After /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. |
/pause | Hold 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. |