> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# Work modes

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


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](#mode-and-workflow-together)). The workflows and how to write your own
are in [24 · Workflows](/oceancode/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](/ocean-code/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](/oceancode/workflows#the-workflow-picker)). 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`):

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](#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](/oceancode/workflows#the-workflow-picker)) 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`):

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](/oceancode/workflows)), 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](#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](/oceancode/workflows)). 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](/oceancode/configuration)). 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`).

| 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. 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](/oceancode/configuration)).

## 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](#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](/oceancode/workflows#auto-and-workflows)) — 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](#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](/oceancode/jev-decisions)).

## 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](/oceancode/workflows#requirements)).

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](/oceancode/workflows)). `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.

```yaml
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](/oceancode/workflows#writing-your-own).
- `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](/oceancode/operations#log-levels-oc_log)). A session whose custom mode's file was deleted runs Model.

## See also

- [24 · Workflows](/oceancode/workflows) — Spec, Build, Review, Secure and Research, the `/workflows` picker, and writing
  your own.
- [02 · Configuration](/oceancode/configuration) — `mode`, `test_command`, `agents.<id>.mode`, `subagent.max_*`.
- [13 · Jev decisions](/oceancode/jev-decisions) — the `work_mode` point.
- [19 · Ocean TUI](/oceancode/tui) and [22 · Ocean TUI reference](/oceancode/tui-reference) — the picker, the badge,
  F2 and the dock.
