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

A work mode decides how agents work together on your prompt. There are three answers to "who decides?":

  • The model — Model, the default. The model decides on its own whether to work alone, call sub-agents or run a workflow. This is Ocean Code as it was before work modes: every tool is offered, any sub-agent type may be called, nothing is added to the prompt, there are no new limits and no badge.
  • Jev — Auto. Once per prompt, Jev picks one of the modes below; when it cannot, simple rules pick.
  • You — a way of working (Solo, Delegate, Pair, Orchestrate), which shapes the lead's turn.

Beside its mode, a session has a workflow setting: off, Auto, or one workflow (Spec, Build, Review, Secure, Research, Goal, Race, or your own), which runs fixed tasks for each prompt. You set it in /workflows, and the two settings combine (Mode and workflow together). The workflows and how to write your own are in 24 · Workflows.

Nothing needs setting up. Until you pick another mode, nothing changes. The nine diagrams drawn, with the six blocks they are built from: Work modes in the Ocean Code documentation.

Picking a mode

F4 or /mode opens the picker: the modes on the left, the highlighted one's picture on the right, and under both, across the whole width, its description, when to use it and its cost. It lists the ways of working only: Model, Auto, Solo, Delegate, Pair and Orchestrate, then your own modes after a ── custom ── divider. Workflows are listed in /workflows, a picker laid out the same way (24). The configured default (Model unless your config's mode names another) is tagged default. When the session's workflow setting is not off, the title row names it: Workflow: Auto · /workflows to change.

KeyWhat it does
↑ / ↓ (k / j)Move. The picture and the text follow at once.
EnterUse this mode for this session.
dMake it the current agent's default: writes agents.<id>.mode to your user oceancode.json (the footer names the agent: d: default for Build).
eCopy a built-in mode to edit, to .oceancode/modes/<id>-copy.yaml (toast: Copied to <path>).
EscClose without a change.

Typed forms: /mode <id> sets this session's mode, /mode default clears it and the workflow setting too. /mode <a workflow id> (/mode spec) turns that workflow on for this session and leaves the mode as it is. The toast reads Mode: <label>; an id the picker and /workflows do not list is refused with the list of the ones they do (crates/ocean-acp/src/extensions/mode.rs:103).

Which mode a session runs, first match wins (crates/ocean-session/src/run/mode.rs:55):

  1. the session's own pick (Enter, /mode <id>);
  2. agents.<id>.mode for the session's agent (d, or F2 › Agent defaults);
  3. the mode key in oceancode.json;
  4. model.

A level that names a workflow ("mode": "spec", an older session, agents.<id>.mode) is skipped here: it sets the workflow setting instead (Mode and workflow together). workflows.orchestrate: "always" with no mode set is read as mode: "goal", and logs that once. A sub-agent always runs under its lead's mode; /mode on a sub-agent's session is refused.

agents.<id>.mode in oceancode.json is the work mode. It is not the mode: line of an agent's markdown file, which says where the agent may run (primary, subagent, all). A config row that sets "mode": "subagent" names no diagram, so that agent runs Model, with a log line.

The badge. Every mode but Model shows a badge on the prompt's top border, at the left after the agent: solo, delegate ≤4, pair, orchestrate ≤8, spec ×3, build, review ×3, secure ×4, research, goal, race ×3; while a workflow's run is active it also names the task the run is on (spec ×3 · validate). Auto shows auto until its first pick, then the pick and why: auto → goal · Jev 0.82 or auto → model · rules: default (crates/ocean-protocol/src/diagram.rs:841). Model shows no badge, so the border looks as it always did. With the workflow setting on Auto and a mode other than Auto, the border shows workflow auto after the mode's badge (pair · workflow auto; under Model, workflow auto alone) until a pick is made for the prompt, then auto → <pick> · <reason>.

Mode and workflow together

A session has two settings: its mode, the way of working, and its workflow setting, which is off, auto or one workflow. They are independent, so you can run Pair with workflow Auto. F4 or /mode <id> sets the mode; /workflows (24) or /mode <a workflow id> sets the workflow setting.

What each prompt does (a fixed mode is any mode but Auto, Model included):

ModeWorkflowWhat runs
anyone workflowEvery prompt is a run of it. The mode does not matter while it runs.
fixed (Pair, say)offA plain turn in that mode. No Jev call.
fixedautoJev picks among the workflows that can run here and "stay in Pair". A workflow starts its run; "stay" runs the prompt as a normal Pair turn.
AutoautoJev picks among the ways of working and the workflows, as Auto always did.
AutooffJev picks among the ways of working only.

When nothing sets the workflow setting (a session that never touched it, a config without the workflow key), it is auto when the mode is Auto and off otherwise. That is how Ocean Code behaved before, so existing setups do not change.

Which workflow setting a session runs, first match wins (crates/ocean-session/src/run/mode.rs):

  1. the session's own setting (Enter in /workflows, or /mode <a workflow id>);
  2. a workflow id in an older session's mode or in agents.<id>.mode, from before this change, when it is the level that decides the mode (the first of session, agent and config that sets one);
  3. the workflow key in oceancode.json (d in /workflows writes it);
  4. a workflow id in the config's mode ("mode": "spec", and workflows.orchestrate: "always", which means goal);
  5. nothing: auto when the mode is Auto, else off.

An id that names no workflow is ignored, with a log line. Sub-agents run under the tree's settings, as before. A workflow's steps use the workflow's own agents and limits; the session's mode does not reach into them.

The modes

Model, Solo, Delegate, Pair and Orchestrate are lead modes: your prompt is an ordinary turn, and the mode only shapes what the lead may do. The workflows — Spec, Build, Review, Secure, Research (24), Goal and Race — are script diagrams, set as the session's workflow setting, not its mode: while one is on, each prompt you type becomes the task of a workflow run. The turn answers at once (race ×3 — started run <id>) and the result arrives later in the session. Delegate, Pair and Orchestrate also add a short block to the lead's prompt naming the agents it may call and the limits.

Model — the model decides

          you
           │
 ┌─────────▼──────────┐
 │ Lead ✎             │
 │ decides: alone,    │
 │ sub-agents or a    │
 │ workflow           │
 └─────────┬──────────┘
           ▼
          you

Nothing is added or hidden, on any provider. Sub-agents may nest 4 deep, as before; only numbers you set in subagent.max_* limit it further.

Auto — Jev picks per task

  you
   │
   ◇ Jev picks a diagram
   │ (the rules, if Jev is off)
   ▼
 the picked diagram runs

See Auto below.

Solo — one agent does everything

          you
           │
 ┌─────────▼──────────┐
 │ Lead ✎             │
 │ reads · edits ·    │
 │ runs the tests  ↺  │
 └─────────┬──────────┘
           ▼
          you

One model, one context. The lead is not offered task, send_subagent_message or workflow, and works off its plan until every row is done. For small or tightly connected changes. Cost ≈ 1×.

Delegate — a lead that calls helpers

                   you
                    │
            ┌───────▼───────┐
            │ Lead ✎        │
            └───────┬───────┘
       ┌────────────┼────────────┐
  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
  │ explore │  │ general │  │ review  │
  └─────────┘  └─────────┘  └─────────┘

The lead does the work and sends side questions to helpers, which return evidence (path:line). task takes only these three types; another is refused with mode Delegate allows: explore, general, review. Up to 4 at once. For everyday work. Cost ≈ 1.2–2×.

Pair — the lead decides, one builder writes

       you
        │
 ┌──────▼─────┐  spec   ┌────────────┐
 │ Lead       │────────▶│ builder ✎  │
 │ decides,   │◀────────│ edits, runs│
 │ reads diff │  diff   │ the checks │
 └──────┬─────┘         └────────────┘
        │ optional
   ┌────▼────┐
   │ explore │
   └─────────┘

The lead never edits (edit, write, apply_patch and hashline are taken away). It writes a change spec, one builder edits and runs the checks, and the lead reads the diff and accepts it or sends corrections. The builder keeps its context between hand-offs; a second running builder is refused (bound: max_builder 1/1). For a strong thinker with a faster, cheaper coder. Cost ≈ 1.3–2×.

Pipeline — hidden

Pipeline (spec, your approval, build, review) left the picker on 2026-11-02: Spec and Build do its two halves with more checks (24). It is still built in: "mode": "pipeline" in oceancode.json still runs it, while /mode pipeline is refused, as /mode takes only the picker's ids.

Orchestrate — a workflow per task

      you
       │
 ┌─────▼──────┐
 │ Lead       │
 └─────┬──────┘
       ├─ 1 scouts  explore ×N
       ├─ 2 plan    from the evidence
       ├─ 3 build   builder ✎ ◀─┐
       ├─ 4 checks  review ×3 ──┘ ↺ ≤ 2
       └─ 5 report  general ──▶ you

For a substantive task the lead runs a workflow: the listed one that fits (its prompt names them), the built-in implement diagram in this shape (not listed), or a script it writes in this shape, adjusted to the task. Short questions stay plain turns. Up to 8 at once. For specs, research and large changes with several parts. Cost ≈ 3–15×.

Goal — loop until proven done

         you: objective
          │
   ┌──────▼──────┐
   │ Plan        │
   └──────┬──────┘
   ┌──────▼──────┐
┌─▶│ Worker ✎    │
│  └──────┬──────┘
│         ◇ 3 skeptics check
└─not yet─┤ ↺ ≤ 10
          ▼
  done · paused · bound reached ──▶ you

The built-in goal workflow: it plans deliverables you can check, then one worker, resumed every pass, works until a panel of skeptics agrees it is done. At most 10 passes; it pauses when the same gaps come back twice. Goal writes no limits of its own: the workflow bounds apply (workflows.max_concurrent_agents, workflows.agent_budget, 02). For long tasks with a clear finish line. Cost ≈ 5–20×. Goal is a workflow: turn it on with Enter on it in /workflows or with /mode goal.

Race — attempts, a judge ranks, you pick

                    you: task
       ┌─────────────┼─────────────┐
 ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
 │ Attempt A │ │ Attempt B │ │ Attempt C │
 │ builder ✎ │ │ builder ✎ │ │ builder ✎ │
 └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
       ◇ tests       ◇ tests       ◇ tests
       └─────────────┼─────────────┘
               ┌─────▼─────┐
               │ judge     │
               └─────┬─────┘
                     ◇ you pick ──▶ applied

Three attempts, each running the sub-agent model (else the session's) in its own copy of the project. The tests run in every copy, the judge ranks the attempts on their diffs and test results, and you pick one (or None). Nothing touches your project until you pick; the winner is applied as a patch. For important changes with tests. Cost ≈ 3× plus the judge.

builder, review and judge are built-in agents, hidden from every agent list; review and judge are read-only. Your own agent file or config row with a prompt or description under one of these names replaces the built-in; a row that sets only model or effort tunes it (crates/ocean-agent/src/agentdef/agent.rs:238).

What you see while a mode works

Every mode shows what it is doing, on the same three surfaces (2026-11-05):

  • The status row names the run, its stage and the helper that works: Goal · round 2/10 · worker-1: Running bash…, Pipeline · step 2/4…, Race · Work · builder-2: working…. It never falls back to a plain Thinking… while a run of this session is active — the lead's turn stays open for the whole run (a Goal, Pipeline, Race or Orchestrate run has no turn of its own), and the row reads the run instead of the silent model.
  • The transcript and the dock carry the run's block and row, with each helper nested under it — for a Goal run too, which before 2026-11-05 showed only a status-bar segment.
  • The Auto badge (auto → goal · Jev 0.82) appears the moment the run starts, with its first frame, not when it ends.

A run's frame goes out at launch, on every helper start and finish, and on every stage; the stage line comes from the script (stage("round 2/10 · verify") in goal.rhai, step N/M in every diagram). The /workflow runs popup and the goal overlay read the same frames, so the helper's tokens there are the child's real counters.

A blocked Goal says why: Blocked: worker-0 failed (max_steps) on the chip, Reason: … in the overlay. A worker cut by the per-helper deadline (workflows.agent_timeout_minutes, 20 by default) does not block the run: the next round resumes the same worker with "You ran out of time. Continue…", and max_rounds still bounds the loop.

Limits

A mode can bound sub-agents three ways: how many run at once in the whole tree, how many one turn may start, and how deep they nest. For each number, your subagent.max_* setting wins, then the mode's own, else there is none; depth falls back to 4 (crates/ocean-protocol/src/diagram.rs:350).

ModeAt oncePer turnDepth
Modelnonenone4
Solo0 (no sub-agents)none4
Delegate, Pair, Pipeline4302
Orchestrate8302
Spec4201
Build4302
Review3101
Secure4101
Goal, Researchnone (the workflow bounds apply)none4
Race3302
Autothe pick'sthe pick'sthe pick's

How each limit acts (crates/ocean-session/src/run/spawn_governor.rs:156):

  • At once covers the lead and every sub-agent under it. When no slot is free, the lead's spawn (or a workflow's) waits, and the dock shows a waiting (4/4 running) row until a slot frees. A deeper sub-agent's spawn is refused rather than queued (bound: max_concurrent 4/4), because its caller already holds a slot. At 0 the task tool is not offered at all.
  • Per turn counts spawns since your last prompt. At the limit a question card asks Sub-agents this turn reached 30. Continue? — Continue (+30) allows 30 more, Stop spawning refuses the rest of the turn. With no one to ask (a headless run) the spawn is refused: bound: max_per_turn 30/30.
  • Depth: at the limit the task tool is not offered, and a spawn is refused with the depth message it always had.
  • Per type: a diagram may limit one agent type ("max": 1 in Pair): bound: max_builder 1/1.

A refused spawn reaches the model as that task call's error; the turn goes on. Switching modes gives the new limit to the next spawn, while children already running keep their old slots, so for a moment old and new can run side by side. Edit the three numbers under F2 › Sub-agents, or in oceancode.json (02).

Auto

Jev is asked when the mode or the workflow setting is Auto. Once per prompt, it answers one typed question: which option fits the task best (crates/ocean-session/src/run/work_mode_jev.rs:127). The options are the ways of working that can run here when the mode is Auto, the workflows that can run here when the workflow setting is Auto, and the session's own mode, meaning "stay", when the mode is not Auto (Mode and workflow together). It answers within Jev's deadline (jev.deadline_ms, 1.5 s by default); the first Auto prompt of a process can take longer while the connection opens. Jev's pick runs when its confidence is at least jev.thresholds.work_mode_confidence (0.6). With Jev off, no TypeSafe key, an error, a time-out or lower confidence, the rules pick instead (crates/ocean-protocol/src/auto_route.rs:31). First the prompt's first word may ask for a workflow — spec, specify, design → Spec; build or implement with .oceancode/plans/ or the word spec in the prompt → Build; review → Review; secure, security, audit → Secure; research, compare, investigate → Research (24) — then:

  1. three or more file paths, or three or more list lines → Orchestrate;
  2. a finish line (until, tests pass, make … pass, suite) → Goal;
  3. one line of fewer than 25 words that is not a question → Solo;
  4. anything else → Model.

When the rules' answer is not among the options (their default, Model, under a fixed mode), the prompt stays in the session's mode. The badge says which decided: auto → goal · Jev 0.82, or auto → solo · rules: short task. Auto never picks a mode that cannot run here (see Requirements). /mode overrides it. Every Jev decision is a row in jev-decisions.jsonl under the point work_mode, which is asked only when the mode or the workflow setting is Auto (13).

Requirements

  • Every workflow needs workflows on (workflows.enabled, the default).
  • Race needs a git project and a test_command in oceancode.json; Build needs the test_command.
  • Spec, Race and Pipeline need an interactive session, because they ask you to approve or pick; headless runs refuse them. Review, Secure, Research and Goal run headless (24).

A mode that cannot run answers the prompt with the reason, for example race needs a git project or spec needs an interactive session (crates/ocean-session/src/run/mode.rs:123).

Race copies. Each attempt runs in a git clone --local of the project under the run's directory (<data dir>/workflows/<run id>/copies/, crates/ocean-session/src/run/workflow/launcher.rs:364), never inside the project. The copy carries your uncommitted changes and untracked files (ignored ones stay out). The winner comes back as one patch applied to the working tree only — nothing is staged — and a patch that does not apply changes nothing; the result then names the copy, which is kept. The other copies are removed when the run ends; a paused run keeps them. Copies of a run that never ended (Ocean Code quit or crashed mid-race, or a pause never resumed) are removed by a later Ocean Code once the run has sat untouched for a day (crates/ocean-session/src/run/workflow/launcher.rs:509). A copy does not include submodules, an absolute symlink in it still points at your real project, and Git LFS may fetch while the copy is made (crates/ocean-session/src/run/workflow/race_copy.rs:48).

Trust. Commands from project files — test_command, and a custom diagram step's command — run through the same bash permission rules as the model's own commands, without a separate repo-trust check. That is how the formatter setting already behaves. Race runs a diff and the tests in each copy through those rules, so with bash: ask it asks for each one: six questions for three attempts.

Custom modes

A mode is one YAML file. A way of working (kind: mode) lives in .oceancode/modes/, a workflow (kind: workflow) in .oceancode/workflows/ beside the .rhai scripts (crates/ocean-app/src/modes.rs:41). Ocean Code reads modes/ in the project and in <config-dir>/oceancode/; workflows are read only from the project (chapter 25). modes/ still reads the older JSONC files (.jsonc, .json) too. The quickest start is e on a built-in: in F4 it copies a mode to .oceancode/modes/<id>-copy.yaml, in /workflows a workflow to .oceancode/workflows/<id>-copy.yaml; edit it and save, and the list shows it at once. The modes/ folders are watched even when they are created after start; the workflows folder is read at start and after each save.

kind: mode                       # a way of working; a workflow is kind: workflow
name: careful                    # lowercase letters, digits and dashes
label: Careful
description: the lead writes, a reviewer checks each change
agents: { explore: {}, review: {} }
lead_prompt: After each change, ask review to refute it before you go on.
limits: { at_once: 2, per_turn: 20, depth: 2 }
  • A file is keyed by its name. A built-in name cannot be reused, and when two files share a name the project's wins; the other file is skipped.
  • agents names real agent ids. A mode may set lead_writes: false (the lead loses its edit tools) and a lead_prompt. A workflow's tasks (task, parallel, loop, gate), every other key and the older JSONC words are in 24 · Workflows.
  • picture is optional: without one F4 or /workflows draws a line per agent or task on the right. picker: false keeps a file out of F4 and /workflows.
  • A file that does not parse or validate is left out, and the engine log names the file and the reason (18). A session whose custom mode's file was deleted runs Model.

See also