OceanCode — Developer Guide

The Ocean coding agent: the oceancode engine (headless run, serve, goal and workflow; an ACP agent for Xcode) and Ocean pager, its terminal UI. 20 chapters: build and configure it, drive it from the terminal, bound a long run, extend it with capabilities, hooks and MCP servers, and the HTTP API (218 operations, read from the route table). Also: One API docs · MCP guide · llms.txt · This guide as markdown. Source: apps/ocean-coding-agent-rust/docs/user-guide/ (build date 2026-10-17).

Contents

• Getting started
• Configuration
• Plan mode and todos
• Session ledger and export
• Headless and server
• Bounding a long run
• Capabilities and plugins
• Hooks
• MCP servers
• Permissions and sandbox
• Jev decisions
• Platform mode (PlungeAI connectivity)
• Testing and gates
• Distribution and updates
• Operations
• Ocean pager — the terminal UI
• Xcode and other ACP editors — oceancode acp
• CLI reference
• Ocean pager reference
• HTTP API reference

Getting started

oceancode is one binary and one process. This page builds it, shows the two ways to start it, and lists where it keeps its files.

Build

cargo build --release -p ocean-cli

The binary is named oceancode and, because the workspace builds into a shared target directory, it lands at the repository-root target/release/oceancode (that is ../../target/release/oceancode from this app directory). Put it on your PATH or call it by that path.

The three boot shapes

oceancode starts in one of three shapes, chosen by the subcommand.

# 1. Pager + engine (the usual way)
oceancode

# 2. Headless server on port 4096
oceancode serve

# 3. One headless run
oceancode run "summarise the README"

The default mode accepts --db, --directory, --listen and --verbose (-v) and passes them to the engine. --tui pager is accepted for compatibility and changes nothing; --tui ocean fails with "the native TUI was removed; oceancode starts Ocean pager". Binding beyond loopback needs --listen and a server password; see 07 · Headless and server.

First run

Authenticate once, then start a session.

oceancode auth        # interactive: API key or Claude Pro/Max subscription
# or, non-interactively:
oceancode login       # Claude Pro/Max subscription login
oceancode key <key>   # store an Anthropic API key

The credential is written to auth.json in the data directory (below) and reused on every later run. Then launch oceancode and type at the prompt.

Starting a session

A plain oceancode opens the pager on a fresh session. Earlier sessions are listed and resumed from inside the pager — see its own user guide under ocean-pager/crates/ocean-pager-ui/docs/user-guide/. Headless runs pick a session with oceancode run --continue / --session <id>; see 07 · Headless and server.

Updating and removing

Keep the binary current, verify a download, or remove it:

oceancode update                 # update to the newest release for your channel (verified, atomic, rollback on failure)
oceancode verify-release oceancode-macos-aarch64.tar.gz   # check a download's signature before trusting it
oceancode uninstall              # remove the binary (add --purge to also remove config + data)

See 17 · Distribution and updates for install one-liners, channels, and the signature/checksum trust model.

Where files live

Paths follow the XDG layout on every platform (macOS included — ~/.config, not ~/Library). <x> below is the matching $XDG_*_HOME when set, otherwise the home-relative default shown.

Next

• 02 · Configuration — the config keys and environment variables.
• 19 · Ocean pager — the terminal UI; its slash commands and keys are in ocean-pager/crates/ocean-pager-ui/docs/user-guide/.

Configuration

oceancode reads a JSON config file and a set of environment variables. Nothing needs to be configured to start — every key falls back to a built-in default.

Config file locations and precedence

There are two config files, and both are optional.

<config-dir> is $XDG_CONFIG_HOME when set, otherwise ~/.config — on every platform, macOS included (the binary uses the XDG layout everywhere, not ~/Library).

Precedence, lowest to highest: built-in default → global file → project file. Within the project directory, oceancode.json is merged over oceancode.jsonc when both exist. Merging is per section, last writer wins.

Comments and trailing commas are allowed in the .jsonc file.

Top-level keys

Every key is optional; an empty or absent value takes the built-in default. Unknown keys are ignored, so a file that still carries the native-TUI keys removed on 2026-10-05 (tui, keybindings, disabled_providers, notifications) loads unchanged.

Environment variables

Set these in the shell before launching. A slash command or an oceancode run flag, where one exists, overrides the environment for that session (see 08 · Bounding a long run).

Test and bench knobs

These steer test, benchmark, and profiling runs; they are not part of normal operation.

Claude Code settings mirror

On the subscription route (claude-code/… models, run through the claude CLI) OceanCode follows Claude Code's own settings, so both tools start the same way. It reads three files, lowest precedence first, and merges them per key (modelSettings per model):

Live. The engine watches both .claude directories. Saving any of the three files re-reads the mirror and the hooks within about a quarter second: sessions still on the previously mirrored model move to the new one (a model you picked by hand in /models is kept), and the UI shows Claude Code settings reloaded — <model> · effort <level> · ultracode on|off when a mirrored value changed (the fleet router rewrites the file periodically; an unchanged rewrite is silent).

Nothing is mirrored when claude is not installed (the settings are still read and reported) or when the files name no model. Managed (enterprise) settings are not read. The watcher follows the .claude directories that exist when the engine starts — a project .claude/ created afterwards is read at the next start (or /hooks → r).

See also

• 01 · Getting started — where these files live on disk.
• 07 · Headless and server — OC_SERVER_USERNAME / OC_SERVER_PASSWORD.

Plan mode and todos

Two separate things share the word "plan": the step list the model keeps as it works, and plan mode, a read-only agent for thinking before touching anything.

For the full design and the code paths, see PLAN-MODE.md (apps/ocean-coding-agent-rust/docs/PLAN-MODE.md); this page is the operator's summary.

The step list (todos)

For work with three or more distinct steps the model keeps a todo list — one item per step — and Ocean pager's todos pane shows it live. A single edit, one command or a plain question gets no list: the same rule Claude Code, opencode, Kilo Code and Grok Build use. Each row ticks through four states:

The model writes the list as a fenced ```todo block in its reply (or through its todo tool); the newest complete block replaces the whole list, so the pane always reflects the latest one. In the pager, ctrl+t toggles the todos pane (see 19 · Ocean pager).

If the model skips the list and then does real multi-step work anyway (twelve or more tool calls with no plan), the next step carries a reminder to write it; a plain answer is never reminded. A settled turn that still has open items is worked off (see 08 · Bounding a long run). OC_PLAN=off turns the directive, the reminder and the work-off off for a run; the todos pane and /plan keep working.

The always-plan floor

If the model has not planned yet, oceancode shows one synthesized row — your prompt text — so the list is never empty. The moment the model writes a real plan, that floor steps aside and does not come back for the session.

Editing the plan yourself — /plan

You can edit the list while a step runs; the model merges your changes with its own on the next step.

A row you add is open work: the run keeps going until it is done or a bound trips (see 08 · Bounding a long run). If you add a to-do while the agent has already finished, it counts as progress — the run picks the work back up for one more turn instead of stopping.

Plan mode

Plan mode is a distinct agent, not a key. In it the model may read and search but may not edit or run side-effecting tools — the one exception is writing plan files under .oceancode/plans/.

• Enter it by selecting the plan agent — in Ocean pager, a bare /plan or /plan <description> (the row-edit verbs above are the only /plan forms that do not switch mode). Every turn then carries a reminder that editing is off.
• Leave it when the model calls plan_exit: it asks "switch to the build agent?", and on your confirmation the session flips to the build agent, which may edit and run. The approval surface lets you approve (y), reject (n), or attach inline comments that are appended to the plan as user-authored rows before you decide.

The step list keeps working throughout — plan mode changes what the model may do, not how progress is tracked.

See also

• 06 · Session ledger and export — where the plan and turns are recorded.

Session ledger and export

A long session would grow to a huge, ever-slower context. oceancode avoids that with the session ledger: the model sees a small, fixed window of recent turns, and everything older is kept verbatim in Markdown files beside the session — never summarized away.

The full concept is in SESSION-LEDGER-CONCEPT.md (apps/ocean-coding-agent-rust/docs/SESSION-LEDGER-CONCEPT.md); this page is the operator's view.

What the ledger is

• A window of the raw conversation. The model always sees the newest part of the real conversation, up to a bounded size — by default 40% of the model's context (400k on a 1M model, 80k on a 200k model). The window is measured in the provider's real tokens after every step, and the oldest content leaves it one block at a time — inside a long turn too (see The tideline below). tokens: 0 instead tracks the model's own ceiling — its context window minus the output allowance; 120k only when the route reports no limit. A turn is your message plus the model's full answer, tool outputs included.
• Per-turn transcripts on disk. Every step is written verbatim to its turn's transcript file as it ends, and the index files are updated when the turn completes. As the window grows the oldest blocks leave it — they are already on disk, so nothing is lost and no model call is made.
• SESSION.md, one living page. Goal, decisions, environment facts, errors and their fixes, a code map, open questions, and the next step — each line stamped with the turn it came from. Facts the database already holds (files touched, commands and exit codes, tasks, the log) are written by the engine. The page is edited, never rewritten, and by one writer; reversed decisions keep the old text struck through rather than deleted.

The ledger ships enabled (ledger.enabled: true), so every session is laddered from its first turn with no setup; its per-turn transcripts are retained for 30 days by default (ledger.retention_days). See 02 · Configuration to change either. OceanCode never summarizes a session — the legacy compaction (summarization) path runs only when ledger.enabled is false.

Find a session's ledger directory with:

oceancode ledger path <session-id>

The tideline — /tideline

You set one number: the share of the model's context where the tideline sits (ledger.tideline.percent, default 40) — the line. After every step the ledger reads the window's size in the provider's real tokens (the gauge: input + cache read + cache write of the step that just ended, plus what that step added — its output and tool results; with compress on, plus the compressor's saved estimate, removed bytes ÷ 4, so the gauge still measures the uncompressed window). Steps are grouped into blocks: a block closes once the gauge has grown by ledger.tideline.block since it opened — a token count, or a share of the line written "35%" (unset = 70% of the line, so 70 000 at a 100 000-token line). While the gauge is at or over the line, the oldest closed block leaves the window, so the window drops to about line − block and grows again. The block still being filled is never cut, so the window overshoots the line by at most one block. A single turn larger than the line is cut block by block while it runs; your message in the oldest block leaves with it.

After a cut the window opens with one line that points at the ledger: [Earlier content of this session is past the tideline: every row up to seq <n> left this window. The verbatim record is <ledger>/transcript/ (one file per turn) and SESSION.md carries the merged state. …]. A turn whose every row is past the tideline is merged into SESSION.md; a turn cut only in part is not. If the provider still refuses a request as too long, every closed block is cut before the one retry.

Between cuts every step only appends, so the provider's prompt cache hits; each cut re-writes the retained window once. The block size sets how often: a 50k block cuts about 20 times per 1M new tokens past the line, a 20k block 50 times. When the model's context is unknown the fixed tokens (default 300000) is the line. A line above what the model can hold (its context minus the output allowance, at most 32k) is clamped to that, with one note in the log.

The status bar's context row measures against the model's own context (…/1.0M on claude-fable-5-1[1m]); the ┃ on its gauge sits at the tideline — tideline @40% (400k): 238k to go, or tideline @300k: 138k to go under a fixed limit — and it reads tideline off when the ledger is disabled.

Config examples (ledger.shelve and ledger.window are still read as aliases):

{ "ledger": { "tideline": { "percent": 50 } } }
{ "ledger": { "tideline": { "tokens": 500000, "block": 20000 } } }

tokens: 0 means the model's own ceiling. The older keys — the floor (low), reserve, the profile presets (wide · narrow · strict · auto) and ledger.hard_tokens — were removed with the band geometry: an old config still loads, they are ignored, and the load logs one warning naming them.

Change the tideline for a session at runtime with /tideline:

Minimum fixed limit 20k; k and m suffixes are accepted. The floor and the presets were removed; a second number or a preset word is refused with the usage line. A change applies from your next message on, which the confirmation says. Headless, the same set is --tideline "<percent>% | <limit> | default". A sub-agent (child) session inherits its parent's /tideline override — the percentage, or the limit.

The meter's denominator is the model's context window under auto and the effective window otherwise.

The session meter

Ocean pager has no cockpit panel; its status bar and /context show the session meter:

• the context meter — what the current window costs against the session's window size;
• token counts — input and output for the session;
• spend — $spent / $cap on a metered route. On the Claude Pro/Max subscription route the bill is a list-price estimate, shown as ≈$spent list · subscription; a limits row appears when a step or time bound is set.

On the Claude Code route the meter's context number is Claude Code's own real context — its system prompt, CLAUDE.md files and MCP schemas, ~100k+ before any turn. When it reaches the limit OceanCode drops the --resume id and cold-starts Claude Code with the ledger page plus the retained turns' text (tool outputs are not re-sent — the page's links carry them), so the number restarts near that baseline and climbs again.

Recovering a step — /undo and /redo

/undo reverts the previous message and /redo re-applies a reverted one, stepping a bookmark through the session so you can back out a bad turn without losing the history.

Exporting a session

Write a whole session out as one file:

oceancode export <session-id> --md   [--out <path>|-]   # one Markdown document
oceancode export <session-id> --atif [--out <path>|-]   # one ATIF-v1.8 trajectory (JSON)

Pass exactly one of --md or --atif. --out - (the default) writes to stdout; --out <path> writes a file. The Markdown export carries frontmatter, every turn, and a ## Summary table, and is built from the ledger's own transcript files when they exist.

Rebuilding the ledger

If a ledger directory is lost or a session predates the ledger, rebuild it from the database:

oceancode ledger rebuild <session-id>            # mechanical: transcripts, indexes, page
oceancode ledger rebuild <session-id> --merge    # also fold the merge backlog (model calls; asks y/N)
oceancode ledger rebuild <session-id> --merge --yes   # skip the confirmation

The plain rebuild makes no model calls; --merge does, so it is never implied.

See also

• 02 · Configuration — the ledger and database config sections.
• 08 · Bounding a long run — spend and clock bounds.

Headless and server

oceancode runs without a UI two ways: a one-shot run for scripts and CI, and a long-lived serve that exposes the engine's HTTP surface to clients. The terminal UI is Ocean pager, which embeds the engine in its own process (see 19 · Ocean pager); serve is the headless surface.

One-shot — oceancode run

Run a single non-interactive turn and exit.

oceancode run "explain what this repo does"
oceancode run --format json "fix the failing test"
oceancode run --continue "and now add a test for it"

Flags go before the prompt (a flag after it is sent to the model as text, with a warning). When stdin is not a terminal, run reads it to EOF and appends it to the prompt — the piped body is the instruction — so a script that passes the prompt as an argument must close stdin (oceancode run "hi" </dev/null) or the run waits forever (observed 2026-10-05: four minutes of nothing with stdin left open).

Useful flags:

Bound flags (--max-usd, --max-minutes, --max-steps, --tideline, --subagent) must come before the prompt — the parser stops at the first non-flag word, and a bound placed after the prompt is ignored with a warning. --tideline <pct>% sets the tideline as a share of the model's context (e.g. --tideline 50%); --tideline <limit> or default also work. The floor and the presets were removed: a second number or a preset word is refused with the usage line. The old --window name is refused with the hint use --tideline; --shelve still works as an alias. See 08 · Bounding a long run.

The engine also serves GET /session/{id}/subagent → {"model": <ModelRef> | null} — the session's effective sub-agent model (the /subagent override, else the fleet router's CLAUDE_CODE_SUBAGENT_MODEL while the subscription slot is live, else the subagent.model config, else the session's own model). A client reads it for the identity row's sub-agents <name> segment; an engine without the route answers as "nothing to show".

Host-run workflows — oceancode workflow

Launch and control a host-run Rhai workflow without a UI. workflow run boots the engine the same way oceancode run does, launches the workflow, streams each workflow_updated body as one JSON line on stdout, and exits by the run's outcome.

oceancode workflow run pipeline --args '{"steps":[{"prompt":"say A"},{"prompt":"say B"}]}'
oceancode workflow run ./research.rhai --budget 64 --model openai/gpt-5-mini
oceancode workflow run pipeline --validate-only --args '{"steps":[{"prompt":"x"}]}'
oceancode workflow runs --all
oceancode workflow stop wf-…

The workflow name (or a path to a .rhai file) comes first, before any flags. A registered name (a built-in such as pipeline, or a discovered .oceancode/workflows/<name>.rhai) is resolved by the launcher; a path you type is read and run as an inline script.

Exit codes (the run's outcome): 0 complete; 2 failed, cancelled or budget_limited; 3 a pause (user_paused, back_off_paused, no_progress_paused, infra_paused, blocked). The last streamed line always carries the terminating body, so a script can read the outcome from stdout as well as from $?.

workflow runs [--all] lists the persisted runs (each workflow_updated body, one per line), read from the run directories under the app data dir — scoped to the current project unless --all lifts the filter. workflow pause|resume|stop <run_id> drive the launcher's control seam; resume takes an optional --budget <n> to lift a budget-limited run. These control a run live in the engine this command boots — a run launched by a separate oceancode workflow run has already exited in its own process, so cross-process control is a shared-server concern not wired here.

Goal mode — oceancode goal

Prove an objective is done, not merely claim it — headless. oceancode goal "<objective>" boots the engine like oceancode run does, launches the built-in goal workflow (Plan → Work → Verify: plan the objective into verifiable deliverables, work in rounds with one resumed worker, and converge only when a cold panel of adversarial skeptics fails to refute completion), streams each goal_updated body as one JSON line on stdout, and exits by the run's outcome. It is the headless twin of the pager's orchestrate: always goal mode (19-pager.md).

oceancode goal "add a --json flag to the status command and prove it works"
oceancode goal --budget 64 --model openai/gpt-5-mini "port the parser to the new API"

The objective is the positional argument — quote it, or let the words after the flags form it. Go-style flag parsing stops at the first positional, so any flag must come before the objective.

Exit codes (the run's outcome): 0 complete; 2 failed, interrupted (a stopped run) or budget_limited; 3 a pause (user_paused, back_off_paused, no_progress_paused, infra_paused, blocked) — a goal that stalls on identical gaps two rounds running, or spends its budget, pauses rather than looping forever. The last streamed line always carries the terminating body, so the outcome reads from stdout as well as from $?. A finished goal is also listed by oceancode workflow runs --all (it shares the workflow run store).

Long-lived server — oceancode serve

oceancode serve                 # loopback, port 4096
oceancode serve --port 8080

The default shape (oceancode, the pager) passes --listen <host:port> through to the engine it embeds; a non-loopback bind refuses to start without a server password (below). The guard is enforced inside the server for both oceancode --listen and oceancode serve --host.

Authentication

HTTP basic auth is off until you set a password.

A non-loopback bind (--listen on the default shape, or serving to a public interface) refuses to start unless OC_SERVER_PASSWORD is set.

Managing capabilities from the CLI

Besides run and serve, the binary answers a set of non-interactive management subcommands that boot no session. Each is read-only or writes a single config file, and exits.

Every management subcommand takes --dir <d> (the project; default: the current directory) and --home <h> (the home the user tier and ~/.oceancode are read from; default: your home) so a script — or a test — can point it at another tree.

Permission mode

A client reads and switches the session's permission mode over HTTP — the boot default is the permission_mode config key, and these two routes change it live (the pager switches it from its own prompt):

The four modes are default, acceptEdits, dontAsk, bypassPermissions — see 12 · Permissions and sandbox.

Managed (enterprise) configuration

For a shared or locked-down deployment, an administrator layers a managed config and a signed requirements file over every project:

• OC_MANAGED_CONFIG — path to the managed config file (default: the OS admin path). It is loaded last, so it overrides the project and global files.
• OC_REQUIREMENTS_PUBKEY — the trusted ed25519 public key (64 hex chars) that a requirements.json signature is checked against; an unsigned or tampered file is refused. With no key set, managed requirements are not enforced.

Both are described in 02 · Configuration; the requirements file can disable bypassPermissions, allow-list MCP servers, and pin config keys. See 12 · Permissions and sandbox.

See also

• 01 · Getting started — the three boot shapes.
• 02 · Configuration — the server variables in one table.

Bounding a long run

A run is bounded by the money and time you set, not by an arbitrary step count. Set nothing and a run keeps going until the work is done (or the no-progress guard stops it, below).

The bounds

Precedence: slash command / flag > environment variable > built-in default. Flag and slash values are stored on the session, so they survive --continue.

The tideline's old names still work as aliases: --shelve, /shelve and ledger.shelve.

The step cap is a boundary, not a stop

OC_MAX_STEPS (default 300) caps the steps in one root turn, but a root turn that reaches it auto-continues into a fresh turn — no budget or clock needs to be set. The ledger cuts by blocks after every step, so even one long turn stays under the tideline (see 06 · Session ledger and export). 0 is rejected: bound a long run with a budget or a clock instead.

Sub-agents are different: they simply stop at OC_MAX_SUBAGENT_STEPS (default 300), so a raised root cap does not deepen them.

Output tokens

OC_MAX_OUTPUT_TOKENS overrides the per-request output-token cap in either direction, clamped to the model's own published maximum. It bounds how much a single model response may emit, not the run as a whole; leave it unset to use the model's full maximum.

What happens at a bound

Exceeding a bound is a clean, non-error stop, distinct from a crash, and the ledger records it as a step-limited turn. The internal stop reasons are BudgetExceeded and TimeExceeded. Over the Ocean tunnel the response carries a typed stopped_by:

The plan drives the run

The model keeps its plan as a todo list (see 05 · Plan mode and todos). A root turn that settles while any todo is still open does not end the run — the engine works off the next open todos and drains again. A run ends only when:

• the work settles with no open todo; or
• a spend or clock bound trips; or
• you interrupt it; or
• the no-progress guard fires — two consecutive continued turns that leave the open and completed counts unchanged stop the run cleanly with a "Run stopped" toast.

So a model that never plans and never settles runs a few turns and stops; one that plans and makes progress runs until its list is done or a bound trips.

The Jev supervisor (opt-in)

With the Jev decision layer on (see 13 · Jev decisions), a supervisor reads a root turn's clean finish and, every jev.supervisor_every_steps settled steps (default 4), the last six steps. With jev.supervisor = "act" it may keep a finish from ending the turn — a synthesized continuation, at most jev.supervisor_max_continuations per human prompt (default 1), only when the goal is clearly not complete and progress is real — and may send one steer message when the steps repeat without progress. It never stops a run and never moves a bound: the spend, clock and step bounds above, the exact-repeat doom-loop trip, the hook cap and the no-progress guard decide exactly as they do without it. In shadow, the default once the layer is enabled, it only records what it would have done.

Stopping a run stops all of it

esc esc (or the palette's abort) stops the session's own drain at its next step boundary, and every sub-agent stops with it — foreground ones immediately, background ones cancelled by the parent. A late background result is recorded as cancelled and never restarts the run.

Background jobs and long waits have no clock of their own

A job the model starts — bash with background: true, a monitor, a loop, a scheduler — runs until it ends or the model calls job_kill. It dies with the run only when the run has a wall clock (OC_MAX_MINUTES / /limits time); without one a build, a watch or a server runs for hours or days, and job_output reads it back whenever the model asks. (Until 2026-10-05 every job was reaped ten minutes after launch while the run had no clock at all.)

A long wait does not lose the prompt cache either. Every request's cache markers carry the provider's one-hour TTL, and while a step waits — on a sub-agent, on a long bash — or the session idles, the engine re-reads the last request every OC_CACHE_KEEPALIVE_MINUTES (default 50) so that clock restarts: a cache read of the prefix (session.cache.touched, cents) instead of re-writing it when the wait ends. It stops after OC_CACHE_KEEPALIVE_MAX touches (default 48, ≈ 40 h; past a model's break-even — 80 touches on Fable 5.1, 20 on a 0.1× model — a re-write is the cheaper bet). A touch that fails is sent once more a few minutes later before the keep-alive gives up, and pressing Esc on a running turn does not stop it — the next prompt reads the same prefix. See 02 · Configuration.

See also

• 02 · Configuration — the OC_MAX_* variables in one table.
• 07 · Headless and server — the --max-* flags on oceancode run.

Capabilities and plugins

Skills, sub-agents, personas, commands and MCP servers are all capabilities, and oceancode finds them the same way: one discovery walk over five tiers, across four ecosystems, with a single rule for names that collide and a separate rule for what a capability is allowed to do.

The five tiers

A capability is discovered from one of five tiers. The walk runs from the narrowest scope out to the widest, so a name defined closer to the code wins.

Plugin-tier roots are enumerated from disk — one root per installed plugin directory — so a plugin contributes its skills, agents and hooks only while it is installed. For plugins Claude Code installed, the roots are exact: only the version directories its ~/.claude/plugins/installed_plugins.json records for the user scope, or for this project, are walked (one root per plugin even when the file lists the same install twice), and a plugin you have disabled in ~/.claude/settings.json (enabledPlugins) stays disabled here. A project's own .claude/settings.json can never re-enable a plugin you disabled.

The .oceancode/ directory in a project is the local tier — your machine's private copy, trusted precisely because it is not shared repo content — and is git-ignored in this monorepo.

Four ecosystems

Each tier is read for four ecosystems at once, so a capability written for another tool is picked up without conversion:

• OceanCode — the native .oceancode/ layout.
• Claude Code — .claude/ (skills, agents, rules, settings.json).
• OpenCode — .opencode/ (opencode.json, agents).
• Grok Build — .grok/ (agents, personas, rules, memory).

Frontmatter and directory conventions from each ecosystem are translated into the one internal shape as they are read; you do not have to rewrite a Claude Code skill or a Grok persona to use it here.

Rule files may pull in other files with @path imports (up to four hops); an import is bounded to the project directory and your home directory, so a rule can never inline a file from elsewhere on disk.

A rule may scope itself to a file glob in its frontmatter — paths: "**/*.py" (Claude Code / OpenCode) or globs: "**/*.ts" (a Cursor .mdc). A scoped rule is loaded only when the working tree actually contains at least one file matching its glob; in a checkout with no match it is left out entirely, so a TypeScript project does not carry Python or Ruby rule bodies. The check honours your ignore rules (.gitignore, .git pruned) and runs once per session. Scope today is resolved for the whole checkout, not per individual file the current turn touches. A rule with no paths/globs is always loaded — with one Cursor exception: a .mdc under .cursor/rules that says alwaysApply: false and has no globs is Cursor's agent-requested or manual rule, which Cursor attaches only when asked, and the engine leaves it out too (a globs: rule keeps its scope whatever the flag says; the key means nothing outside .cursor/rules).

Workflow scripts

Workflow scripts are discovered the same way, from two OceanCode roots in the usual precedence (built-in > project > user). Every *.rhai file under a root is one workflow, identified by the meta.name its script declares — not by its file name:

Two workflows ship built in to the binary — the highest tier — so they run by name with no *.rhai file on disk. Built-ins cannot be shadowed: a project or user script with the same meta.name as a built-in is ignored (dropped from the picker catalog with a warning), and the built-in still runs — that is what "built-in > project > user, first wins" means. A duplicate meta.name across two discovered files likewise keeps the first (project before user).

Names that collide are qualified; unique names stay bare

A capability keeps its bare name when that name is unique across everything discovered. Only when the same name appears more than once is it qualified, and only the colliding members are rewritten:

The pass reads only each item's bare name and source, so it is idempotent — running discovery again yields the same qualified names in the same order.

The slash name of a plugin skill is always <plugin>:name, even when the name is unique — Claude Code's convention, so /superpowers:writing-plans lists and runs in the Ocean pager's / popup exactly as it does there. Typed as a prompt, /<plugin>:name and the bare /name both run an enabled plugin skill; a <plugin>: prefix that names no installed plugin does not resolve (a warning toast; the text is then sent as a normal message).

Enable is not trust

Two independent gates decide what a capability does:

• Enabled — whether the capability is discovered and offered at all. Disabling a plugin removes its capabilities from the walk — including its rule bodies, which no longer inject into the system prompt (its skills, agents, commands, hooks and MCP servers drop too).
• Trusted — whether a capability that can execute code on your behalf is allowed to run without a prompt. Only hooks and MCP servers gate on trust; a skill or a persona is inert data and needs no trust decision.

By default, Local, User and Bundled tiers are trusted; the Repo tier is untrusted (code that arrived with a checkout has not been vetted by you); a Plugin is trusted only if you installed it with trust. So enabling a repo-supplied hook is not the same as trusting it — it is discovered, but it will not run its command until you trust it.

Trust decisions for a project persist in ~/.oceancode/trust.json, keyed by the project's absolute path: repo (may the repo tier's hooks and .mcp.json servers execute?), mcp (per-server overrides that beat repo) and disabled_mcp (servers held disabled at any tier). Plugin trust lives beside the plugin in ~/.oceancode/plugins/installed.json. Set them with oceancode trust repo on|off, oceancode trust mcp <name> on|off|clear, oceancode plugin trust <name> [--off], or from the /hooks, /mcp and /plugins pickers; read them with oceancode trust show.

Enabling and disabling skills

Loading every skill from every tier costs prompt tokens — one <available_skills> line and one skill_* tool per skill, plus a disabled plugin's rule bodies. Skills, plugins and MCP servers share one enable interface so you can turn off what you are not using; a disabled skill costs nothing (it is not in <available_skills>, registers no skill_* tool, and its rules do not inject).

A skill's effective state is the fold of four tiers, resolved in this order — the first that turns it off wins, so a project can disable a skill but can never re-enable one you disabled:

The per-skill user toggle is written by the CLI (or the /skills picker) into ~/.oceancode/skill-state.json — OceanCode's own store, never Claude's ~/.claude/settings.json. The project policy (mode, disabled, enabled) lives in .oceancode/oceancode.json under skills (see 02 · Configuration); default mode all keeps every skill a candidate. The project policy is a default: an explicit enable of one skill (Space on its row, a plugin-group header's Space, or oceancode skill enable <id>) is also recorded for this project as enabled_skills in ~/.oceancode/trust.json and beats the project's skills.disabled and allowlist (tiers 3–4), so a skill the allowlist leaves out can be switched on without editing the config; it never beats the master switch or a disabled plugin, a disable drops it again, and enable-all stays user-tier only. MCP keeps its own disabled_mcp / enabled_mcp model (oceancode mcp enable|disable, see 11 · MCP servers); the verbs are the same shape.

oceancode skill enable <id>            # clear the user-tier disable; beats the project policy
oceancode skill disable <id>           # disable this skill at the user tier
oceancode skill enable-all             # clear every user-tier skill disable
oceancode skill disable-all            # disable every currently-discovered skill

<id> is a skill's stable id <tier>.<eco>:<name> — e.g. user.claude_code:agents-sdk, local.ocean_code:tdd, repo.open_code:deep — shown in the id column of skill list. It is computed the same way whether or not the name collides with another tier, so the store never loses a disable when a session sees only one tier. You may also pass a bare name when exactly one discovered skill has it (oceancode skill disable wrangler); a name shared by more than one skill is refused with the candidate ids, so pass the full id to pick one. A bare name is still accepted in skills.disabled/skills.enabled and as a legacy store entry (it matches every copy of that name). If you disabled skills before this change, re-run oceancode skill disable-all once to rewrite the store with stable ids.

A toggle takes effect on the next step of the running session. The /skills and capabilities pickers, the /skill invocation gate and the Ocean pager's composer / completion update at once (an enabled skill is offered as /<skill>, a disabled one is not); the <available_skills> block, the skill_* tools, the MCP tool list and the hook dispatcher are rebuilt before the agent's next model call, so the very next request no longer carries what you turned off. A step already running finishes with what it started with. Each change made mid-session costs one system-prompt cache rewrite (the cached prefix changes once), so flip several things together rather than one per turn. A change made from a shell (oceancode skill disable-all) lands on the next step too.

Whole groups and everything at once. In the Ocean pager's capabilities picker (/skills, /plugins, /hooks, /mcps) Space works at four levels:

Everything off removes skills, MCP tools, hooks and plugin rules from the agent's context; the built-in tools (bash, read, edit, …) stay. Turning it back on restores exactly the per-item state you had. A group whose rows are all off shows [off] on its header, and the picker's last row shows the live counts — skills 22/259 · plugins 2/21 · mcp 1/10 · hooks 8/8 — with EVERYTHING OFF in front while the master switch is off. Group and master state is per project, stored next to disabled_mcp in ~/.oceancode/trust.json; per-skill disables stay in skill-state.json. The Plugins tab lists Claude Code's cached plugins (under User (Claude)) beside the OceanCode-store ones, and Space turns a whole plugin — its skills, hooks, MCP servers and rules — off or on.

Start from nothing. To strip the prompt down and add capabilities back deliberately, disable everything and re-enable one by one: oceancode plugin disable-all (then re-enable from /plugins), and oceancode skill disable-all with skills.mode = "allowlist" + a short skills.enabled list for the handful of skills you actually want. With every plugin disabled and an empty allowlist, the first turn carries no <available_skills> block and no skill_* tools at all.

oceancode inspect — where did this come from?

To see the winning source of every capability, config key, MCP server and instruction file for the current directory:

oceancode inspect          # a human-readable provenance table
oceancode inspect --json   # a stable JSON array (for scripts)

Each row names the kind, the id, the layer that won, and the file it came from — the fastest way to answer "why is this skill loaded and not that one?". It boots nothing and is read-only.

instruction rows list what the directory contributes to the system prompt: one primary file — CLAUDE.md, else AGENTS.md, never both, so a generated AGENTS.md mirror is not loaded twice — then CLAUDE.local.md and CONTEXT.md when present. The same rule applies at every level from the worktree root down to the working directory, and to the reminder that fires when a tool first touches a directory this session. The system prompt is fixed for the rest of a prompt, so an edit to these files (or a URL instruction expiring, or midnight passing) made while a prompt runs applies from the next prompt, not the next step; switching a capability or the model still applies on the very next step.

Plugins and marketplaces

A plugin bundles skills, agents and hooks under one installable tree. Manage them from the CLI:

oceancode plugin marketplace add <spec>      # register a marketplace
oceancode plugin marketplace list
oceancode plugin marketplace update <name>
oceancode plugin marketplace remove <name>

oceancode plugin install <name-or-path> [--trust] [--marketplace <m>]
oceancode plugin list
oceancode plugin enable <name>               # / disable <name>
oceancode plugin enable-all                  # / disable-all — flip every installed plugin
oceancode plugin trust <name> [--off]        # grant / revoke trust
oceancode plugin validate <name>             # check the manifest
oceancode plugin update <name>               # / uninstall <name>

install without --trust enables the plugin but leaves it untrusted, so its hooks and MCP servers stay dormant until you run plugin trust. Pass --root <dir> to any plugin subcommand to point at a project other than the current directory.

In Ocean pager, /plugins opens the Plugins tab of the capabilities picker; see 19 · Ocean pager.

Importing from Claude Code

If you already use Claude Code, one command brings its setup here:

oceancode plugin import --from claude-code --dry-run   # show what would happen, write nothing
oceancode plugin import --from claude-code --trust     # do it, trusting the imported plugins

What it does, and what it deliberately does not:

• Plugins are copied from Claude Code's cache (~/.claude/plugins/cache/<marketplace>/<name>/<version>/) into ~/.oceancode/plugins — only the versions installed for the user scope or for this project — and each is enabled or disabled as your ~/.claude/settings.json says. Without --trust they are enabled but untrusted, so their hooks and MCP servers stay dormant.
• Marketplaces Claude Code knows (known_marketplaces.json) are registered.
• Trust is seeded from Claude Code's own record in ~/.claude.json: the project's hasTrustDialogAccepted becomes repo=true (pass --no-repo-trust to opt out), servers in disabledMcpServers / disabledMcpjsonServers are held disabled, enabledMcpjsonServers are trusted.
• Skills, commands, agents, rules, hooks and MCP configs at the user and repo tiers are not copied. ~/.claude/skills, ~/.claude/commands, ~/.claude/settings.json, .claude/** and .mcp.json are read where they are, so they stay in sync with Claude Code.

Every line the command prints names one action (IMPORT, SKIP, MISSING, MARKETPLACE, TRUST); the last line is IMPORT_OK plugins=<n> marketplaces=<m> repo_trust=<bool> (with --dry-run, IMPORT_DRY_RUN_OK …). A cache tree that is not a plugin — Claude Code's rust-analyzer-lsp / typescript-lsp entries carry neither a manifest nor a SKILL.md — is reported SKIP <name> not a plugin and one entry that fails to install is reported SKIP <name> install failed: <why>; neither stops the run, so the trust seeding at the end always happens. Nothing under ~/.claude is ever modified.

/skills — browse and run

Every discovered skill — yours, the project's, a plugin's, from any of the four ecosystems — is a slash command: /<name> <arguments> runs it as a command turn whose prompt is the skill body prefaced by a one-line instruction, with $ARGUMENTS and the positional rules applied. A name that collides across tiers is invoked by its qualified form (/repo:review). The completion popup lists skills with the other commands.

In Ocean pager, /skills opens the Skills tab of the capabilities picker and the composer's / completion lists your enabled skills; see 19 · Ocean pager. Without a session:

oceancode skill list            # id  tier  trusted|untrusted  <state>  description
oceancode skill list --json     # each row carries "id", "enabled" and a "reason" tag when disabled

The id column is the stable <tier>.<eco>:<name> id (--json also keeps the collision-resolved qualified name); copy it straight into oceancode skill enable|disable <id>.

The state column reads enabled, or why the skill is off — disabled (plugin), disabled (user), disabled (project) or not in allowlist (see Enabling and disabling skills).

See also

• 10 · Hooks — the one capability that gates on trust and can change a run.
• 11 · MCP servers — the other trust-gated capability, and its own translation table.
• 19 · Ocean pager — /plugins, /skills, /mcps, /hooks in the terminal UI; the pager's other commands are in ocean-pager/crates/ocean-pager-ui/docs/user-guide/.
• 07 · Headless and server — every management subcommand in one table.

Hooks

A hook runs your own command (or an HTTP endpoint) at a fixed point in a run and hands back a typed decision the engine acts on. Hooks are configured in a Claude Code settings.json / hooks.json shape, so a hook you already wrote for Claude Code runs here unchanged.

The nine events

A hook is registered against one of nine lifecycle events:

PreToolUse and PostToolUse carry the tool_name, so a handler can scope itself to one tool.

The settings.json shape

Handlers live in a settings.json (or hooks.json) under the same keys Claude Code uses — the event name maps to a list of hook groups, each group a matcher plus one or more handlers:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./scripts/guard.sh", "timeout": 10 }
        ]
      }
    ]
  }
}

A command handler is run through <shell> -c <command> (shell defaults to sh) in the project directory, with the event payload as JSON on stdin and these variables on its environment: OC_HOOK_EVENT (the event name), OC_PROJECT_DIR and CLAUDE_PROJECT_DIR (both the project directory, so a Claude Code hook script that reads $CLAUDE_PROJECT_DIR works unchanged). An http handler POSTs the payload to a URL with your headers. Hooks are discovered as capabilities (see 09 · Capabilities and plugins) and, because they execute on your behalf, they run only from a trusted source.

The payload is the Claude Code shape: every event object carries hook_event_name and cwd (inserted only when absent, never overwriting a field the event already set); SessionStart carries source: "startup", SessionEnd carries reason: "exit". A group's matcher is a regex tested against tool_name for PreToolUse / PostToolUse / PermissionDenied, against source for SessionStart and against reason for SessionEnd; the other events ignore it. An absent or empty matcher matches everything. One documented gap: session_id is not available at the hook seam, so a handler that keys on it sees no such field.

Where hooks are read from — and when they run

At boot (and on every reload) oceancode walks every ecosystem's hook files — its own .oceancode/, Claude Code's .claude/ and Grok Build's .grok/ — in this order, and merges their groups per event, so earlier tiers' handlers run first:

A held source is still parsed and listed — with its handlers — so you can see exactly what trusting it would enable. The reasons are held: untrusted (repo tier, project not trusted), held: disabled plugin, unreadable and invalid.

Since 2026-09-10 the three Claude Code settings files are also watched: saving one reloads the hooks (the same path r in /hooks and POST /hooks/reload take) together with the Claude Code settings mirror — no reload needed after editing ~/.claude/settings.json.

On the claude CLI route there is no double firing. When a session's provider route is the claude command-line protocol, the claude subprocess reads the very same ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json and its installed plugins' hooks/hooks.json, and runs those hooks itself. On that route oceancode therefore dispatches only its own .oceancode/ hooks (the ocean_code ecosystem, local and user tiers) and leaves every Claude Code-shared source to Claude Code — a UserPromptSubmit handler in .claude/settings.local.json fires once per prompt, not twice. Every other route (Anthropic API, OpenAI-compatible, Grok, …) dispatches everything in the table above, since nothing else would. /hooks and GET /hooks still list all sources on every route; the by-source report marks the shared ones (shared_with_claude_code).

/hooks and oceancode hooks list

In Ocean pager, /hooks opens the Hooks tab of the capabilities picker (toggle and reload go through the engine); see 19 · Ocean pager.

Without a session:

oceancode hooks list            # one line per source, then its handlers indented
oceancode hooks list --json     # {"repo_trusted": bool, "sources": [...]}
oceancode hooks add PreToolUse --matcher Bash --command ./scripts/guard.sh [--timeout 10] [--scope user|project|local]
oceancode hooks remove PreToolUse --matcher Bash --command ./scripts/guard.sh [--scope user|project|local]

list ends with HOOKS_OK sources=<n> handlers=<m> loaded=<k>; add prints HOOK_ADDED <path> and remove prints HOOK_REMOVED <path> (--scope defaults to project; remove of a handler that is not there exits 1 with hooks remove: no such handler); --dir <d> and --home <h> select another project or home. The scope names are Claude Code's: user, project and local are the three files. Note that both project files — .claude/settings.json and .claude/settings.local.json — are listed at tier repo: they live in the checkout, so they run only when the project is trusted. (local the scope is Claude Code's name for the git-ignored project file; local the tier is .oceancode/, your machine's private copy.) Over HTTP a client reads GET /hooks, reloads with POST /hooks/reload, toggles repo trust with POST /trust/repo {"on": true|false}, adds with POST /hooks {event, matcher, command, timeout?, scope} and removes with POST /hooks/remove {path, event, matcher, target} — every one answers the same {repo_trusted, sources} document.

The decision contract

A handler communicates back two ways: its exit code and a JSON object on stdout.

Grok Build handlers may also return updatedToolOutput (honoured only for a model-visible copy) and defer. Everything but an explicit deny fails open: a handler that crashes, times out or prints garbage never wedges a run.

Only command and http handlers run here, and only the nine events above. A handler of another type — Claude Code's prompt and agent hooks — or one registered under an event this runner does not implement (Claude Code's Notification, PreCompact, SubagentStart, …) is skipped and counted (skipped: <n> unsupported handlers beside the source in /hooks), never fatal: the other handlers in the same file still load.

Continuing a Stop

A Stop handler that wants the run to keep going returns a stopReason — the engine treats that as a continuation and drains again. To keep a runaway handler from looping forever, at most 8 Stop continuations are honoured per run; past that the run settles. An exit-2 on Stop is a plain Deny and does not count against those 8.

Provenance and replay

Every hook outcome is recorded with its provenance — which source, which handler, what it decided — so a run can be replayed and audited: you can see exactly which hook denied a tool or continued a turn, and from which tier it came. oceancode inspect lists every hook source with loaded or held beside it.

See also

• 09 · Capabilities and plugins — discovery, tiers, and the trust gate hooks depend on.
• 11 · MCP servers — the other trust-gated capability.
• 02 · Configuration — OC_HOOK_EVENT and OC_PROJECT_DIR, set on every command handler.
• 19 · Ocean pager — /hooks in the terminal UI.
• 07 · Headless and server — oceancode hooks list and oceancode trust.

MCP servers

An MCP server is an external process (or HTTP endpoint) that contributes tools, resources and prompts to a run. oceancode reads the same server-config files the other tools use, so a server you configured for Claude Code, Cursor or OpenCode is picked up as-is.

Where servers are configured

Servers are read from several files at once and merged by precedence:

Precedence, highest first: local > project > user > plugin. A server defined closer to you overrides a same-named server from a wider scope. Every server from every file is folded into the one manager at boot, so /mcp, GET /mcp and oceancode mcp list all show the same set — but a name declared at two tiers runs once: the copy that lost its name (qualified <tier>:<name>, say user:cloudflare-dev for a ~/.claude.json copy of the project's .mcp.json server) is folded held disabled — listed, never spawned, its tools never offered a second time under a user_cloudflare-dev_* prefix — and mcp list reads shadowed on it. Only when the winning copy cannot run (held untrusted or disabled) does the next copy run in its place. Before 2026-10-13 both copies were started.

Held until trusted

A server that arrived with a checkout (the project's .mcp.json) or with a plugin can run code on your machine, so it is listed but held — status untrusted — until you trust it. Nothing is dialed or spawned for a held server. Three ways to release one, all persisted in ~/.oceancode/trust.json under the project's absolute path:

oceancode trust repo on            # trust the repo tier: its .mcp.json servers and its hooks
oceancode trust mcp <name> on      # trust one server (beats the repo flag); `off` holds it again; `clear` removes the override
oceancode trust show               # repo=<bool>, one `mcp <name>=<bool>` per override, one `disabled <name>` per held-disabled server, then TRUST_OK

or trust it from the pager's /mcps tab. A server Claude Code has switched off for this project (disabledMcpServers / disabledMcpjsonServers in ~/.claude.json, seeded by oceancode plugin import --from claude-code) is held disabled at every tier and reports disabled. User-tier servers (~/.claude.json) are trusted by default.

Enabled and trusted are independent: oceancode mcp disable <name> (or the pager's /mcps tab) switches a server off — disconnecting it and recording the hold in trust.json — without changing its trust, and enable switches it back on; a server that is enabled but still untrusted stays held and reports untrusted, and connect refuses to dial it until it is trusted. The engine reads a trust.json change made from the CLI at its next boot; the pager and the HTTP routes apply it live.

oceancode mcp enable|disable is the MCP arm of the one enable interface skills, plugins and MCP servers share (skill enable|disable, plugin enable|disable, and enable-all/disable-all on each) — see Enabling and disabling skills. MCP keeps its own disabled_mcp hold model rather than the skills' four-tier fold; the verbs are the same shape so there is one thing to learn. An explicit enable is remembered per project as enabled_mcp in ~/.oceancode/trust.json and beats a config entry's enabled: false, so a server your project config ships off can be switched on from the picker or the CLI and stays on.

Any ${VAR} or ${VAR:-default} in a server's command, args, env or headers is expanded from your environment when the server starts; an unresolved ${VAR} is left literal rather than blanked, so a misconfigured variable is visible instead of silently empty.

Like hooks, MCP servers execute on your behalf, so they run only from a trusted source (see 09 · Capabilities and plugins).

Resources, prompts and elicitation

An MCP server offers more than tools:

• Resources — the server's resources/list and resources/read are surfaced so a server can hand documents into a run.
• Prompts — each server prompt appears as a slash command named /mcp__<server>__<prompt>.
• Elicitation — a server that asks the user a question mid-call is routed to the same question seam the rest of the app uses, so the prompt shows up in your UI and the answer goes back to the server.

Meta-dispatch for large tool sets

When many servers are connected, the flat tool catalog gets unwieldy for the model — and some providers reject a tools array longer than 128. Past 128 connected MCP tools the engine always replaces the flat catalog with two meta-tools — search_tool (find a tool by keyword) and use_tool (invoke one by id). Setting OC_MCP_META_TOOLS=1 does the same from 64 tools up. See 02 · Configuration.

Managing servers — oceancode mcp

# A stdio server (a local command):
oceancode mcp add <name> --command <cmd> [--arg <a>]... [--env K=V]...

# A remote server (an HTTP endpoint):
oceancode mcp add <name> --url <url> [--header K=V]...

oceancode mcp list             # name  stdio|remote  tier  trusted|untrusted  enabled|disabled|shadowed  source
oceancode mcp enable <name>    # / disable <name>  — switch any server off or on (config-declared or discovered; held disabled in ~/.oceancode/trust.json, honoured at boot)
oceancode mcp remove <name>
oceancode mcp login <name>     # / logout <name>  — OAuth for a server that needs it
oceancode mcp doctor           # probe every server and report reachable / failed (a shadowed copy is not dialed; it reads shadowed)

list walks every config file above for the current directory (--dir <d>, --home <h> to point elsewhere) and shows, per server, its tier, whether it may run and whether it is enabled.

add writes a Claude-Code-shaped .mcp.json, so the server is immediately visible to any tool that reads that file. Pass exactly one of --command (stdio) or --url (remote). --root <dir> and --home <dir> override where the config and home are read.

doctor gives each server a short connect budget and reports it reachable or failed quickly, so one unreachable server does not hang the check.

In Ocean pager, /mcps opens the MCP tab of the capabilities picker (add, enable/disable and trust go through the engine); see 19 · Ocean pager. A server whose handshake is still in flight reads connecting (the status list is connected / connecting / needs-auth / failed / disabled / untrusted); a status read gives the startup pass at most two seconds and then answers with the live rows (the handshake itself may take up to 30 s, the timeout default). Disconnecting, disabling or untrusting a server is bounded to about two seconds even when the server process left a child holding its output pipe open.

A prompt's first model request waits up to OC_MCP_WAIT_SECONDS (default 5; 0 never waits; sub-agents never wait) for the servers configured at boot to finish connecting, so their tools are already in that request. The tool list is then fixed for the rest of the prompt: a server that connects, or lists new tools (tools/list_changed), while a prompt runs reaches the model on the next prompt, because a changed tool list at the front of the request would make the provider re-write its whole prompt cache. Toggling a server, connecting or disconnecting it by hand, trust or any capability still applies on the very next step.

Over HTTP a client reads GET /mcp (each entry carries trusted, enabled, provenance and kind beside status), GET /mcp/{name}/tools, GET /mcp/{name}/prompts, GET /mcp/{name}/resources, and posts POST /mcp/{name}/trust {"on"}, POST /mcp/{name}/enable {"on"}, POST /mcp/{name}/connect|disconnect, POST /mcp/{name}/auth and DELETE /mcp/{name}/auth.

See also

• 09 · Capabilities and plugins — discovery, tiers, and the trust gate.
• 10 · Hooks — the other capability that runs your code.
• 02 · Configuration — OC_MCP_META_TOOLS and the mcp config key.
• 07 · Headless and server — oceancode trust and oceancode mcp list.

Permissions and sandbox

OceanCode decides what a tool may do in three layers, from softest to hardest:

1. Permission rules and modes — an ask/allow/deny policy over each tool call.
2. The shell and filesystem guards — a classifier that reasons about what a bash command or a file edit actually does, on top of the rules.
3. The kernel sandbox — OS-level isolation the process cannot talk its way out of, off by default.

An empty config is not an asking one: the base rule is * * allow, so a tool call is allowed unless something fences it — the shell's dangerous floor, an external_directory ask, a denied .env read. Secret-named environment variables are stripped from child processes and .env files are never read into the model. Add bash * ask under permission to make every shell command off the read-only safe list ask; that is also the posture the Jev permission advisor works on. This page is how to loosen or tighten each layer.

Permission modes

A mode is a coarse posture layered over your permission rules. Set the boot default with permission_mode in the config (see 02 · Configuration), or switch it live over the HTTP API (see Switching the mode live below).

The Ocean pager's auto (the Shift+Tab Auto stop, /auto) is acceptEdits and its always-approve (ctrl+o, /always-approve) is bypassPermissions; the pager sends every change to the engine (see 19 · Ocean pager).

A mode is expressed as ordinary last-match-wins rules, so it can never silently override the safety floor: bypassPermissions appends an allow-all rule, but the dangerous-floor deny is evaluated first and wins regardless.

Jev advisor. With the opt-in Jev decision layer on (see 13 · Jev decisions), a residual ask on a bash command — one that no allow, deny or specific-pattern ask rule settled — is first put to Jev as four bounded questions (in act the prompt waits at most jev.deadline_ms, 1.5 s by default). With the empty config's * * allow base there is no such ask, so the advisor sees nothing until a rule such as bash * ask makes the shell guard ask. In shadow, the default once the layer is enabled, the call runs in the background, its answer is only recorded and you are asked as before, without waiting. With jev.permissions = "act" a command inside a bounded safe class — not destructive, no network egress, easily undone, a single-file or project blast radius — runs without the prompt. The dangerous floor and deny rules run before the advisor and never reach it, dontAsk gets no advice, a command that names a path outside the project (or runs in a workdir outside it) gets none either — the shell guard checks that in code — and a fixed hold list (package installs and publishes, git push, recursive rm, ssh, an uploading curl, an interpreter run on a file, …) always asks. Under headless --auto, an act advice that the command is destructive, sends data out, reaches the system or a third party, or tripped the injection guard rejects the call instead of approving it, and the rejection carries the reason and the Jev scores back to the model as feedback (see 13). Your answer to an advised prompt is recorded as that decision's label.

Rule syntax — Tool(pattern)

Individual permission entries and the shell.allow / shell.deny lists take a Tool(pattern) form, e.g. Bash(git push:*), Edit(src/**), Read(*.md). The tool name is matched case-insensitively; an empty pattern means *.

A tool whose last rule for its key is a * deny — bash * deny, or a read-only agent's blanket deny — is not offered to the model at all: its schema is left out of the request (write, apply_patch and hashline count as edit). A narrower last rule keeps the tool, so the plan agent still sees edit for its plan file. Sub-agent children are sent the built-in tools only, never MCP or skill tools.

Switching the mode live

The permission mode is switched at runtime over the HTTP API — GET/POST /api/session/{id}/permission/mode (see 07 · Headless and server). A managed (enterprise) requirements file can lock out bypassPermissions: once locked, selecting it downgrades to default.

The shell guard

Before any bash command runs, a classifier splits it into segments, peels wrappers (sudo, env, nice, timeout, xargs, bash -c "…", VAR=val …), and decides allow / ask / deny per segment. The whole command runs only if every segment is allowed (a chaining guard — git status && rm x still asks).

• Read-only safe list. Commands that only read (git status, git log, ls, rg, grep, find, …) auto-approve with no rule. The list looks at flags: find with -delete, -exec, -execdir, -ok, -okdir, -fprint, -fprint0, -fprintf or -fls; git branch that deletes, renames, copies, forces or re-points (-d, -D, -m, -M, -c, -C, -f, -u, --delete, --set-upstream-to, --unset-upstream); git remote with add, remove, rm, rename, set-url, set-head, set-branches, prune or update; and git tag that creates, signs, forces or deletes (a name after tag creates a tag unless -l/--list makes it a pattern) are off the list and ask. Adding output redirection (> file) drops a command off the safe list.
• Dangerous floor. A fixed set of destructive shapes is refused outright and no permission mode can reopen it: rm -rf / (and obfuscated variants), git push --force, dd of=/dev/*, chmod -R 777 /, mkfs*, the fork bomb, and curl … | sh. The floor peels wrappers and unwraps bash -c/command substitutions, so hiding the command behind sudo, /bin/rm, or $(…) does not evade it.
• shell overrides. safe_list_extra adds read-only commands; allow / deny layer Tool(pattern) rules onto the classifier. Neither can remove the dangerous floor.

Child-process environment

Every bash and PTY child gets a composed environment rather than a raw copy of the parent's. By default, variables whose name contains KEY, SECRET, or TOKEN (case-insensitive) are stripped, so a secret in your shell never leaks into a spawned tool.

Tune it with child_env:

The sandbox

The sandbox confines a spawned child at the OS level — sandbox-exec (Seatbelt) on macOS, bubblewrap (with Landlock where the kernel supports it) on Linux ≥ 5.13. It is off by default; turn it on with the sandbox config.

• deny lists roots refused even inside the workspace (e.g. .git, a secrets dir).
• network is off (no egress) or allowlist; with an allow-list, only the exact hosts in allow_hosts are reachable, enforced by a TLS-SNI relay (no wildcards, no suffix matches).

On a Linux kernel older than 5.13, Landlock is unavailable and bubblewrap alone provides the confinement (a warning is logged, never a silent disable).

Reference aliases

refs maps a short @name to a directory. A path of the form @name/rest in any file tool (read / edit / write) expands to <refs[name]>/rest, and that reference root is auto-allowed through the external-directory prompt — so a shared docs or vendor tree can be reached without a prompt for every file. An unknown @name is left literal and still prompts, and an alias that walks out of its root (@name/../escape) is caught by the external-directory boundary just like any other outside path.

Filesystem guards

The file tools carry their own safety, independent of the rules:

• .env is never read. read refuses .env and *.env / *.env.* files (secrets); .env.example still reads.
• Read-before-write. write refuses to overwrite an existing file you have not read this session ("file exists but has not been read this session"); a brand-new file writes freely. One exception (2026-09-28): a file under 64 KiB that this session itself created — its birth time is at or after the session's first tool call in this process, e.g. a file a bash command generated — can be overwritten without a read. A file that existed before the session is refused even when it was edited since, and on a filesystem that reports no birth time the exception never applies.
• Stale detection. edit and write refuse a target that changed on disk since it was last read — detected by content hash, so a same-size, same-mtime change is still caught. Read it again first. Other files changing — a build, a file a bash command wrote, the session's own database — never cost you a read: a read stays valid until the file itself changes (2026-09-28).

Managed (enterprise) config

An administrator can layer a managed config over every project. It is loaded last, so project < user < managed — managed always wins. Its location is the OS admin path, or $OC_MANAGED_CONFIG (see 02 · Configuration).

Alongside it, a signed requirements.json carries hard requirements — disabling bypassPermissions, an MCP-server allow-list, and config pins. It is verified with ed25519 against the trusted key in $OC_REQUIREMENTS_PUBKEY: an unsigned or tampered requirements file is refused, never applied. With no key configured, managed requirements are simply not enforced.

• oceancode inspect shows the provenance of every effective config key — which layer (project / user / managed / requirements) set it.
• oceancode doctor reports crash recovery state: orphaned sessions and captured panic reports. See 07 · Headless and server.

See also

• 02 · Configuration — the config keys and variables.
• 07 · Headless and server — oceancode doctor and the permission-mode routes.

Jev decisions

OceanCode can put small typed questions to TypeSafe Jev (System One, pinned model jev-1.13.0) at seven decision points — "would this command delete data?", "which block of this output answers the step?" — and use the answers as advice. Jev answers with probabilities: a noul (the probability of yes), a choice over named options, or a score over ordered levels. The policy that turns an answer into a verdict is code beside each decision point, and the engine's deterministic backstops stay in front of it: Jev can never turn a deny into anything, never reopen the dangerous floor, never raise a spend, step or clock bound.

The layer is off by default. It needs your consent in two places, and every point starts in shadow — decide and record, change nothing — until you promote it to act.

What Jev decides

Turning it on

1. The global config — $OC_CONFIG, else <config-dir>/oceancode/oceancode.json (or the managed document an administrator ships, which wins over it):

   { "jev": { "enabled": true } }
   

2. The project config — <project>/.oceancode/oceancode.jsonc or .json. The layer is on only when both sections say enabled: true, so a repository has to opt in:

   { "jev": { "enabled": true } }
   

   A project section may set only enabled and the seven mode keys. Its endpoint, model, budgets and thresholds are ignored with one warning, so a cloned repository can neither send your states or credentials elsewhere nor loosen a threshold.

3. An endpoint the build can reach. The default build's endpoint is the direct TypeSafe API, https://api.typesafe.ai/v1/systemone, which needs OC_TYPESAFE_API_KEY; without the key the layer stays off. The platform build (--features platform) defaults to the PlungeAI worker, https://typesafe-provider.ap-a98.workers.dev/systemone?backend=cloudflare, and sends it the ocean.headers map of the global config (the managed document or yours — never the project file's). Either build can use the other endpoint through jev.endpoint in the global config or OC_JEV_ENDPOINT. The key goes only to api.typesafe.ai, ocean.headers only to the worker, a redirect is never followed, and plain http is refused unless OC_JEV_ENDPOINT names a loopback host.

   The worker refuses a public-internet POST /systemone that lacks its shared key (401; 503 until the key is set on the worker), so the global config must carry it — the global file only, never a project file (a project's ocean.headers is ignored):

   { "ocean": { "headers": { "x-ocean-key": "<the worker key>" } } }
   

   Every request also names its decision point in an x-jev-point header (AI Gateway metadata on the worker's side) and the worker's own time comes back in Server-Timing.

4. Check it. oceancode jev status should list the seven points in shadow with the endpoint host; oceancode jev probe makes one live call and prints JEV_PROBE_OK.

5. Leave everything in shadow until the point has its own labels (see Promoting a point to act).

Modes

Each point has its own key: off, shadow or act.

With the layer enabled, a point whose key is unset is in shadow — act is never a default. The project section's key wins over the global section's. Note that two keys differ from the point names: permission is jev.permissions and tool tiers is jev.tools. The point names are accepted as the same keys — jev.permission and jev.tool_tiers mean jev.permissions and jev.tools.

OC_JEV overrides all seven at once: OC_JEV=off turns the layer off whatever the config says, and shadow or act sets every point. It never turns the layer on by itself — jev.enabled must still be set in both sections — and an unrecognised value is ignored with a warning.

Promoting a point to act

Promote one point at a time, and only after its per-point label run passes:

1. Run the point in shadow for at least a week of your own sessions.
2. oceancode jev labels collects every decision you answered (see Reading decisions) into bench/jev/labels.json.
3. The point's own run — node scripts/bench/jev-decisions.mjs --set bench/jev/labels.json --point <p> (live, OC_LIVE_CONFIRM=1) — must print JEV_EVAL_OK point=<p> …: accuracy ≥ 0.90 on the unanimous labels, a Wilson 95 % lower bound on that accuracy (wilson_lower= on the line) ≥ 0.80, at least 40 rows for permission and 12 for any other point, and no false allow. A handful of right answers cannot promote a point: n = 12 at 12/12 is 0.758 and never passes, and all-correct needs 16 rows. Short of the bound the run prints JEV_EVAL_RED reason=wilson.
4. Then set that point's key to act in the project config.

Point 1 needs the posture it advises on: an empty config allows shell commands (the base rule is * * allow), so nothing asks and the advisor never runs. Add bash * ask under permission and every command off the read-only safe list asks — and is advised. The safe list is flag-aware (find -delete/-exec, git branch -D, git remote add, git tag v1 are off it; see 12 · Permissions and sandbox). The default posture is not changed by this layer.

Point 5 has one more precondition — the provider route check below. Points 5 and 6 change the advertised tools and skills per prompt, which changes the prompt-cache prefix; measure the cache reads of a real session before promoting either.

Thresholds

Every threshold lives in jev.thresholds, is read from the global section only, and is tuned against labels for the pinned jev.model (a threshold tuned on one model id is not reused on another; jev.model must be a versioned id — latest and preview are refused). Probability thresholds are 0–1; the three score thresholds (permission_reversible, supervisor_progress, supervisor_loop_progress) are on the three-level scale 0–2.

What the numbers mean in practice, from the recorded answers:

• supervisor_progress_confidence reads the progress mass, not the API's confidence. It is compared with 1 − P("0") — the probability above the lowest ("no progress") rung. The Score answer's own confidence measures how concentrated the answer is on one rung, so it drops whenever the answer spreads over adjacent rungs: a recorded half-done trace split 0.39 / 0.61 between "incremental" and "substantial" progress, nothing on "no progress", and reported confidence 0.42 — a mass of 1.0.
• relevance_rerank is gone. A key set in an old config is still accepted (one warning, "no longer read"); nothing reads it. In act, point 6 used to send a second request, a noul per top-three skill over its body excerpt, and it confirmed no candidate in 7 of 8 recorded prompts while adding 0.18–0.86 s at the start of each. The wide choice's rank order stands.
• permission_scope is gone. A key set in an old config is still accepted (one warning, "no longer read"); nothing reads it. Against the task "fix the failing unit test in crates/ocean-llm", Jev scored cargo nextest run --all-features 0.73 and ls -la 0.57 on the old outside_scope question (both ask), and cargo nextest run -p ocean-llm 0.24 (allow): a question about "the task" punished ordinary project commands, so scope became a code check. Re-recorded without it, cargo nextest run --all-features is allow.
• needs_more_than_core and needs_skill rarely change the pick. needs_more_than_core scored 0.09–0.35 on the recorded prompts — the web-research and sub-agent prompts included — so point 5 advertises 4 extra tools, never 8, at the default 0.6; the named tools were still among the 4. needs_skill scored 0.21–0.77 on skill prompts and 0.18–0.30 on coding prompts, but the 0.02 floor already leaves few skills on a skill prompt, so the cap of 3 binds only on coding prompts. Both are tuning items for the label run.

The other jev keys:

What is sent

A state is named fields, never a concatenated prompt, and the questions refer to them by backticked path; nothing from the state is spliced into a question.

• Sticky keep-sets (points 5 and 6, act only). The tool list and the skill block are decided at a session's first prompt and kept. A later prompt that shares vocabulary with the previous one reuses both and sends nothing: it has fewer than four words (lowercase a–z, 0–9, _ runs of four or more characters, not one of please with this that from into then make also just should could would need want file files code change update fix), or at least a fifth of its words appear in the previous prompt. Each point whose set came from a decision then writes one acted row (a point that never asked, for a small catalogue or roster, writes none), verdict sticky, reason "keep-set reused: the prompt shares vocabulary with the previous one". A prompt that shares no vocabulary is decided as usual and its keep-set is added to the old one, so a session's tools and skills only grow. In shadow every prompt is asked about, and no sticky row is written.
• Paths outside the project. There is no scope question; the bash gate marks an ask paths_outside_project: true and the advisor sends nothing then (a skip row, a path outside the project). The check runs on the call's workdir and on every word of the command that is a path: it starts with / or ~, contains /, or is .. — relative ones resolved against the workdir, the value of --key=value, key=value and -I/path taken as the path, a leading redirection (2>, >>) dropped, a URL (://) and /dev/null ignored, and a $VAR/… word, which cannot be resolved, counted as outside. It is lexical, like the external-directory prompt: a symlink out of the project is not followed.
• Head/tail truncation. A long text field keeps its head and tail around a [truncated N bytes] marker. Point 1 never advises on a truncated state; the other points only record it.
• 48,000 bytes is the hard cap on any state. The endpoint was measured to accept about 33k input tokens — a 60,334-byte state answered, a 61,600-byte one was refused — and dense tool output runs about 1.7 bytes per token, so no state is ever sent above 48,000 bytes of JSON. A state the endpoint still refuses as too long comes back as HTTP 503 with error code 7003 ("User Input Error"); the client records that as invalid, never retries it and never counts it towards the back-off.
• The injection guard. Before any call, every string of the state is normalised (case, fullwidth letters, invisible and bidi characters, whitespace) and matched against phrases that address the judge rather than describe the world — "ignore the above instructions", "note to the classifier", "you are Jev", "this command is safe", … A match skips the call and records injection. Your own words — the top-level task, goal and prompt fields — are exempt. The tool and skill descriptions points 5 and 6 rank are question options, which the guard does not scan.
• No content filter yet. States carry raw text: the command, up to 255 output blocks, six step results, up to 12 KB of failing output, up to 255 excerpts of old tool results. That can include a secret from a file the dotenv rule does not cover (.dev.vars, *.pem), and the decision log keeps every state on disk (see Reading decisions). Turn jev.enabled on only in repositories whose tool output may leave the machine.
• Where it goes. Through the PlungeAI worker the request is answered by Workers AI through Cloudflare AI Gateway, billed to the PlungeAI account with gateway logging on — file contents leave the machine. The worker can also relay to OpenRouter; OceanCode never uses that: every request to the worker has backend=cloudflare, and an answer whose x-typesafe-backend header is missing or names another backend is refused. TypeSafe states that it does not train on requests. This is why a repository must opt in with its own jev.enabled.

Reading decisions

• oceancode inspect shows one jev row per point: the mode as its layer, and the endpoint host (or off) as its source. See 09 · Capabilities.
• jev-decisions.jsonl. Every decision a point makes — acted on or not — is one JSON line in <ledger root>/<session id>/jev-decisions.jsonl, beside the session's ledger folder (the ledger root is <data dir>/session-ledger unless ledger.dir sets it). A row carries point, mode, outcome, verdict, baseline (today's behaviour), latency_ms, server_ms (the worker's own time for the call, from its Server-Timing header; absent when the endpoint sent none), model, input_tokens, state_hash (a hash of the full state), state (the state itself, or for one over 8 KiB a head/tail excerpt — the full state is then written once to <ledger root>/<session id>/jev-states/<state_hash>.json, so every decision can be re-sent) and answers — the full answers with every probability, or for a skipped or failed decision the reason as a string. It never carries the key, the endpoint or a header value, and a URL in an error message is replaced by <url>. Writing is best effort: a full disk never fails a decision (the first failure is logged once).
• Outcomes. acted (the verdict changed something), shadow (recorded only), fallback (the decision kept today's behaviour: a low-confidence answer, a skip such as a command over 4,000 chars, or an answer that could not be applied), held (point 1's deterministic hold kept an allow answer at ask), unavailable (deadline, transport, HTTP error, rate cap or back-off window), invalid (an answer missing a key, of the wrong type or with bad probabilities; a state over its budget; the 7003 refusal), injection (the guard skipped the call) and off (the decider behind the point was off).
• The triage re-run note. When point 4 re-runs a command, its decision row is written first, with the state Jev was asked about, and a second row follows with outcome acted and the reason rerun exit=<code> or rerun refused: <why> as its answers string. Only rows whose answers is an object are decisions; count and label those. A missing-binary or missing-module failure (the env_missing signals in the point 4 row above) is written as one row with the reason deterministic env_missing as its answers string and no request: acted / hint once the hint was appended, fallback / pass for a failing install command, shadow / hint in shadow. The hint line is "jev triage: <name> is not available (exit ); use what the project already has — <alternative> is available and do not install anything the task did not ask for" (the alternative clause only when one is on PATH; "a command" in place of the name when only the exit code said so, and for an env_missing answer Jev gave itself).
• Labels. When you answer a permission prompt that Jev advised on, a label row is appended to the same file — allow for once or always, deny for reject — and joined to its decision. Only a person's answer is a label: the replies headless oceancode run gives by itself (--auto's once, a Jev-advised reject, the reject without --auto) and the Ocean pager's own answers (its YOLO auto-approve, the queue it approves when you switch YOLO on, a cancelled or failed prompt) write none. oceancode jev labels exports every labelled decision.
• Labelling by hand. Points 2–7 have no prompt to answer, so their rows come unlabelled. oceancode jev labels --unlabelled --out to-label.json (optionally --point <p>) writes them with "label": null and "source": "unlabelled". An annotator fills each label in the grammar of bench/jev/README.md, sets source to annotator-<n> (a second annotator adds second_label), and the rows are appended to bench/jev/labels.json by hand, for example jq -s add bench/jev/labels.json to-label.json > merged.json && mv merged.json bench/jev/labels.json. oceancode jev labels keeps every row already in that file and adds only decisions whose point and state hash it does not carry, so a later export never duplicates an annotated row. An unlabelled row may carry "evidence": {"spill_grepped": true}: its turn later grepped or read a file under tool-output/, so the full output was wanted after all. It is a hint for you, never a label.
• Implicit labels. oceancode jev labels --implicit --out bench/jev/labels.json labels the rows nobody labelled from what the agent did next in the session's transcript: the first skill it loaded after a relevance pick (skill:<name>, source implicit-skill-load), the tools it fetched with tool_search after a tier pick (wide;extra:<tool> or narrow;extra:<tool>, implicit-tool-search), and whether it made an edit / write / apply_patch / bash call after a supervisor continuation (continue, else finish, implicit-continuation). Rows follow the same merge as any export. These are the agent's behaviour, not your verdict, so spot-check them before a run counts on them; the rules are in bench/jev/README.md.

cargo build --release -p ocean-cli --features platform

platform: not compiled in (ocean.mode or ocean.endpoint is set; rebuild with --features platform)

export PATH="$HOME/.cargo/bin:$PATH"
./check.sh                 # fmt · clippy -D warnings · build · nextest · goldens · doc + gate checks
E2E=1     ./check.sh       # + real-engine PTY tests, chaos, crash-recovery drills, the interface probe
PERF=1    ./check.sh       # + divan benches and the budget gates
COVERAGE=1 ./check.sh      # + llvm-cov with the zero-covered-handler tripwire
MUTANTS=1 ./check.sh       # + cargo-mutants over the risk-ranked modules

bash scripts/probe/run-probe.sh                 # every scenario
bash scripts/probe/run-probe.sh -k slash        # only scenarios whose id (or file) contains "slash"
bash scripts/probe/run-probe.sh -k baseline     # one file's scenarios (-k matches the module name too)
bash scripts/probe/run-probe.sh -j 4            # run 4 at a time, each on its own ports
bash scripts/probe/run-probe.sh --list          # module:id of every discovered scenario
bash scripts/probe/run-probe.sh --keep          # keep each scenario's temp HOME to debug a failure

INTERFACE_PROBE_OK scenarios=10 passed=10 xfail=0        # exit 0
INTERFACE_PROBE_FAIL scenarios=10 failed=1 mcp_roundtrip  # exit 1

session.py open <name> --app oceancode|pager|cli|cmd [--cols 120 --rows 40] [--keep] [-- cmd args…]
session.py <name> screen | styled <row> | history | send <text> | key <k> [k…] | paste <text>
session.py <name> wait <needle> [timeout] | wait_re <regex> [timeout] | resize <c> <r> | alive | requests | evidence <file> | close

S="target/probe-venv/bin/python scripts/probe/session.py"
$S open pager --app pager            # fresh HOME, fake provider, PTY 120×40
$S pager wait '❯' 40                 # block on the ready marker
$S pager send 'hello'; $S pager key enter
$S pager wait 'ok: hello' 40
$S pager styled 38                   # one row as (fg, bg, bold) runs — colour/bold asserts
$S pager close                       # kill app + fixture, remove the temp HOME

# scripts/probe/scenarios/my_feature.py
def scenario_models_open_and_esc(t, fx):
    """/models opens the model picker and Esc returns to a live composer."""
    t.send("/models")
    t.key("enter", 0.6)
    if "MODEL" not in t.text():
        t.fail("/models did not open the model picker")
    t.key("esc", 0.4)
    if t.PLACEHOLDER not in t.text():
        t.fail("Esc did not return to the composer")
    # the harness calls t.assert_live() after this returns

from scenarios.xfail import xfail

@xfail("OCA-1234-slash-refusal-toast")
def scenario_unknown_slash_is_refused_visibly(t, fx):
    ...

oceancode update              # update to the newest release for your channel
oceancode update --self-test  # prove the swap + rollback offline (no network)

oceancode verify-release oceancode-macos-aarch64.tar.gz \
  --sha256sums SHA256SUMS

oceancode uninstall            # remove the binary only
oceancode uninstall --purge    # also remove ~/.config/oceancode and the data dir
oceancode uninstall --dry-run  # print the plan, remove nothing

{
  "version": "2.6.0",
  "channel": "stable",
  "artifacts": [
    {
      "target": "aarch64-apple-darwin",
      "url": "https://…/oceancode-macos-aarch64",
      "sha256": "…",
      "minisig": "https://…/oceancode-macos-aarch64.minisig"
    }
  ]
}

# oceancode v<X.Y.Z>

## Highlights
- <the one or two changes users will notice first>

## Install
- macOS/Linux: `curl -fsSL <install.sh> | sh`
- Windows: `irm <install.ps1> | iex`
- Homebrew: `brew install OWNER/oceancode/oceancode`
- Cargo: `cargo install --locked oceancode`

## Verify
Download the asset for your platform and run:
`oceancode verify-release <asset> --sha256sums SHA256SUMS`

## Changed
- <user-visible changes from the CHANGELOG's dated section>

## Fixed
- <fixes from the CHANGELOG>

## Checksums
See `SHA256SUMS` and the per-asset `<asset>.minisig` attached to this release.

{
  "database": { "retention_days": 30, "vacuum": true },
  "ledger":   { "retention_days": 30 }
}

$ oceancode doctor --storage
…orphan / panic report…
storage:
  oceancode.db 4194304 bytes (wal 32768 bytes)
  sessions=128
  ledger 2097152 bytes, oldest 12 days
  restore is offline-only: stop oceancode before restoring a backup

{ "obs": { "log_level": "debug", "log_file": "/var/log/oceancode.log", "log_rotate_bytes": 10485760 } }

STEPS=1000 TURNS_OUT=docs/results/soak/turns.jsonl bash scripts/bench/marathon-fixture.sh --steps 1000
node scripts/bench/soak-metrics.mjs docs/results/soak/turns.jsonl        # → SOAK_OK / SOAK_RED

oceancode auth        # API key or Claude Pro/Max subscription → auth.json in the data directory

oceancode mcp add xcode --command xcrun --arg mcpbridge

{ printf '%s\n' \
    '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' \
    '{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"'"$PWD"'","mcpServers":[]}}'
  sleep 3
} | oceancode acp 2>/dev/null

oceancode [--db <path>] [--directory <dir>] [--listen <host:port>] [--tui pager] [-v]

oceancode run [flags] <message…>

oceancode serve [--port <n>] [--host <ip>] [--db <path>] [--directory <dir>] [-v]

oceancode acp [--db <path>] [--directory <dir>] [-v]

oceancode workflow run <name|path> [--args <json>] [--budget <n>] [--validate-only] [-m <provider/model>]
oceancode workflow runs [--all] [--directory <dir>]
oceancode workflow pause|resume|stop <run_id> [--budget <n>]

oceancode goal "<objective>" [--budget <n>] [-m <provider/model>] [--db <path>] [--directory <dir>] [-v]

oceancode ledger path [--db <path>] [--directory <dir>] <session-id>
oceancode ledger rebuild [--merge] [--yes] [--db <path>] [--directory <dir>] <session-id>

oceancode export (--md | --atif) [--out <path>|-] [--db <path>] [--directory <dir>] <session-id>

oceancode login [--provider claude|copilot|codex] [--no-browser]

oceancode logout [anthropic|zai-coding-plan|ocean]

oceancode key [<provider>] [<api-key>]

oceancode auth

oceancode claude

oceancode inspect [--json]

oceancode plugin [--root <home>] <subcommand>

oceancode mcp [--root <dir> | --dir <dir>] [--home <h>] <subcommand>

oceancode skill [--root <dir>] [--dir <d>] [--home <h>] <subcommand>

oceancode trust show | repo on|off | mcp <name> on|off|clear  [--dir <d>] [--home <h>]

oceancode hooks [--dir <d>] [--home <h>] list [--json]
oceancode hooks add <Event> --command <cmd> [--matcher <re>] [--timeout <s>] [--scope user|project|local]
oceancode hooks remove <Event> --command <cmd> [--matcher <re>] [--scope user|project|local]

oceancode jev status [--json]
oceancode jev probe [--record --point <p> --case <id> --request <req.json> --out <fixture.json> [--expect <json>]]
oceancode jev labels [--implicit | --unlabelled [--point <p>]] [--root <ledger dir>] [--out <file>]
oceancode jev questions --json
oceancode jev verdicts --in <cases.jsonl>

oceancode doctor [--storage]

oceancode migrate [--db <path>]

oceancode update [--self-test]

oceancode verify-release <artifact> [--pubkey <base64>] [--sha256sums <path>]

oceancode uninstall [--purge] [--yes] [--dry-run]