Configure
Work modes
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.
| Key | What it does |
|---|---|
↑ / ↓ (k / j) | Move. The picture and the text follow at once. |
Enter | Use this mode for this session. |
d | Make it the current agent's default: writes agents.<id>.mode to your user oceancode.json (the footer names the agent: d: default for Build). |
e | Copy a built-in mode to edit, to .oceancode/modes/<id>-copy.yaml (toast: Copied to <path>). |
Esc | Close 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):
- the session's own pick (
Enter,/mode <id>); agents.<id>.modefor the session's agent (d, or F2 › Agent defaults);- the
modekey inoceancode.json; 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):
| Mode | Workflow | What runs |
|---|---|---|
| any | one workflow | Every prompt is a run of it. The mode does not matter while it runs. |
| fixed (Pair, say) | off | A plain turn in that mode. No Jev call. |
| fixed | auto | Jev 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. |
| Auto | auto | Jev picks among the ways of working and the workflows, as Auto always did. |
| Auto | off | Jev 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):
- the session's own setting (
Enterin/workflows, or/mode <a workflow id>); - 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); - the
workflowkey inoceancode.json(din/workflowswrites it); - a workflow id in the config's
mode("mode": "spec", andworkflows.orchestrate: "always", which meansgoal); - nothing:
autowhen the mode is Auto, elseoff.
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 │
└─────────┬──────────┘
▼
youNothing 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 runsSee Auto below.
Solo — one agent does everything
you
│
┌─────────▼──────────┐
│ Lead ✎ │
│ reads · edits · │
│ runs the tests ↺ │
└─────────┬──────────┘
▼
youOne 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 ──▶ youFor 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 ──▶ youThe 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 ──▶ appliedThree 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 plainThinking…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).
| Mode | At once | Per turn | Depth |
|---|---|---|---|
| Model | none | none | 4 |
| Solo | 0 (no sub-agents) | none | 4 |
| Delegate, Pair, Pipeline | 4 | 30 | 2 |
| Orchestrate | 8 | 30 | 2 |
| Spec | 4 | 20 | 1 |
| Build | 4 | 30 | 2 |
| Review | 3 | 10 | 1 |
| Secure | 4 | 10 | 1 |
| Goal, Research | none (the workflow bounds apply) | none | 4 |
| Race | 3 | 30 | 2 |
| Auto | the pick's | the pick's | the 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. At0thetasktool 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 spawningrefuses 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
tasktool 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": 1in 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:
- three or more file paths, or three or more list lines → Orchestrate;
- a finish line (
until,tests pass,make … pass,suite) → Goal; - one line of fewer than 25 words that is not a question → Solo;
- 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_commandinoceancode.json; Build needs thetest_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. agentsnames real agent ids. A mode may setlead_writes: false(the lead loses its edit tools) and alead_prompt. A workflow's tasks (task,parallel,loop,gate), every other key and the older JSONC words are in 24 · Workflows.pictureis optional: without oneF4or/workflowsdraws a line per agent or task on the right.picker: falsekeeps a file out ofF4and/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
- 24 · Workflows — Spec, Build, Review, Secure and Research, the
/workflowspicker, and writing your own. - 02 · Configuration —
mode,test_command,agents.<id>.mode,subagent.max_*. - 13 · Jev decisions — the
work_modepoint. - 19 · Ocean TUI and 22 · Ocean TUI reference — the picker, the badge, F2 and the dock.