For AI agents: an index of this guide is available at https://www.plungeai.com/guide/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. The developer documentation is at https://www.plungeai.com/docs/llms.txt.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.
Feedback

oceancode is one binary: oceancode [subcommand] [flags] [args]. With no subcommand it starts Ocean TUI. acp runs it as an editor agent, and serve, run, goal and workflow run it headless. 01 · Getting started explains the three boot shapes. This page lists every subcommand, its flags and its exit codes.

Flag syntax

Most engine commands parse flags with a port of Go's flag package: the default shape, serve, acp, migrate, run, workflow, goal, ledger, export, login, logout, key, auth and slack connect. Go's rules apply:

  • -name and --name are the same flag. A value is written --name value or --name=value. Single-letter flags cannot be bundled: -vc is one flag named vc.
  • Parsing stops at the first argument that is not a flag, or at a bare --, which is dropped. Everything after that point is positional, even if it looks like a flag.
  • A boolean flag never takes the next argument; turn one off with --name=false. Integer flags accept Go's base prefixes (0x1000, 0o10000, 0b…) and _ separators.
  • -h/--help prints Usage of <name>: and the flag list to stderr, then exits 0. An unknown flag, a missing value or a bad value prints the error and the usage to stderr, then exits 2.

The capability and maintenance commands (plugin, mcp, skill, trust, hooks, jev, inspect, doctor, update, verify-release, uninstall, claude) parse their arguments by hand. Write their flags with two dashes, exactly as shown. Most of them reject --help with a usage error (exit 1). update ignores --help and runs a real update, so never try oceancode update --help.

Global flags

--version must be the first argument. --data-dir and --fake-llm-sse are removed from the whole command line before the subcommand is chosen, so a run prompt that contains the words --data-dir x loses them.

FlagTypeDefaultMeaning
--version——Print oceancode <version> (<build stamp>) and exit 0. Needs no database, config or terminal. -v is not an alias: it means --verbose.
--data-dir <dir>stringthe app data dirWhere auth.json and the other per-install state live, for commands that boot the engine. Also --data-dir=<dir>.
--fake-llm-sse <file>string, repeatablenoneTest hook: replay a recorded provider SSE body for each turn, in order, repeating the last one. Also --fake-llm-sse=<file>.

OC_DETERMINISTIC=1 is read at the same point: it pins the clock and seed that ids are minted from, so two runs produce identical id sequences. Every invocation except --version checks for orphaned sessions left by a crashed run. When it finds any, it prints one line to stderr: note: <n> orphaned session(s) from a previous run — run `oceancode doctor` for details.

Common engine flags

--db, --directory and --verbose are not global; each command declares them. They mean the same thing everywhere, so the per-command tables below omit them.

FlagTypeDefaultMeaningTaken by
--dbstringoceancode.dbPath to the session database.the default shape, run, serve, acp, workflow run/pause/resume/stop, goal, ledger, export, migrate
--directorystringcurrent directoryWorking directory. For workflow runs it is the project to filter by.the same, minus migrate, plus workflow runs
--verbose, -vbooloffTrace every outbound LLM provider request/response to stderr, with credentials masked.the default shape, run, serve, acp, workflow run and its control verbs, goal

Exit codes

CodeMeaningWhere
0Success, or -h/--help on a Go-flag command.all
1The command failed. The message is printed to stderr as error: <message>.all
2Flag parse error (unknown flag, missing or bad value).Go-flag commands

oceancode run exits with a typed code once its turn has started. A failure before that (boot, flag validation, an empty message) is exit 1. A turn that ends while background sub-agents or a workflow it started still work does not end the run: run waits for them and for the turns their results start, and exits on the last. A workflow that pauses is not waited for; resume it later.

CodeMeaningStop reason(s)
0finishedfinished, waiting
2permission rejectedpermission_rejected
3budgetbudget
4timetime
5no progressno_progress, max_steps, doom_loop
6errorerror, hook_blocked; also a --json-schema that cannot be satisfied
130interruptuser_interrupt

oceancode workflow run and oceancode goal exit by the run's final status:

CodeStatus
0complete (and a --validate-only check)
2failed, cancelled, interrupted, budget_limited, or any unrecognised status
3a pause: user_paused, back_off_paused, no_progress_paused, infra_paused, blocked

Exit 2 from run can be a permission rejection or a flag error; the stderr text tells them apart.

oceancode (no subcommand)

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

Execs Ocean TUI, which runs the engine inside its own process. stdout must be a terminal; otherwise it fails with stdout is not a terminal — use `oceancode serve` for headless serving. The TUI binary is looked up in this order: OC_TUI_BIN, then next to oceancode (also next to its target if oceancode is a symlink), then PATH. Here --verbose becomes the TUI's --debug.

FlagTypeDefaultMeaning
--listenstring127.0.0.1:4096HTTP bind address handed to the TUI. A non-loopback address needs OC_SERVER_PASSWORD.
--tuistringemptyKept for old scripts: empty or tui is accepted; ocean is refused (the native TUI was removed on 2026-10-05), and any other value is an error (only `tui` exists). Falls back to OC_TUI.

See 19 · Ocean TUI.

oceancode run

oceancode run [flags] <message…>

Runs one non-interactive turn and exits with the typed code above. Flags must come before the message, because a flag after it is sent to the model as text; a bound flag placed after the message also prints a warning that the run is not bounded by it. When stdin is not a terminal, run reads it to EOF and appends it to the message, so close stdin (</dev/null) when the prompt is only an argument. An empty message fails with you must provide a message.

FlagTypeDefaultMeaning
--agentstringemptyAgent to use.
--model, -mstringemptyModel to use, provider/model.
--variantstringemptyModel variant (provider-specific reasoning effort, e.g. high, max).
--titlestringtruncated promptSession title.
--continue, -cbooloffContinue the last session.
--session, -sstringemptySession id to continue.
--resume-title, -rstringemptyResume the most recent session whose title matches this text.
--forkbooloffFork the session before continuing. An error unless --continue or --session is also given.
--autobooloffAuto-approve permissions that are not explicitly denied (dangerous!).
--output-formatstringtextstream-json (NDJSON per event), json (one buffered result object), or text. Takes precedence over --format.
--formatstringdefaultDeprecated. default = text; json = the stream-json framing.
--toolsstringallRestrict the advertised tools to these comma-separated ids. An unknown id is an error.
--disallowed-toolsstringemptyRemove these comma-separated tool ids from the advertised set.
--allowstringemptyAppend allow permission rules, e.g. "Bash(git *),Edit(src/**)".
--denystringemptyAppend deny permission rules (last match wins, so a --deny beats an overlapping --allow).
--append-system-promptstringemptyAppend this text to the run's system context.
--json-schemastringemptyValidate the model's final JSON against this JSON Schema (a file path or inline JSON). On a mismatch the model is re-prompted with the validation errors, up to a retry limit. Prints the validated object; exits 6 if the schema cannot be satisfied.
--max-usdstringunsetUSD bound for this session: a number, off, or subscription (no bound; spend shows the list-price estimate).
--max-minutesstringunsetWall-clock bound: minutes, 90m, 8h, 2d, or off.
--max-stepsstringunsetStep bound per turn, 1..=1000, or default to clear a stored override.
--tideline, --shelvestringunsetThe Session Ledger tideline: <pct>% (a share of the model's context), <limit>, or default. --shelve is the older spelling.
--windowstring—Removed. Any value fails with --window was renamed: use --tideline.
--subagentstringunsetThe model this session's sub-agents run, provider/model.
--atifstringemptyWhen the turn ends, write the session's ATIF-v1.8 trajectory (JSON) to this path.

See 07 · Headless and server and 08 · Bounding a long run.

oceancode serve

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

Starts the engine with its HTTP surface only and no UI. The banner goes to stdout and diagnostics to stderr. A non-loopback --host without OC_SERVER_PASSWORD is refused before anything boots.

FlagTypeDefaultMeaning
--portint4096TCP port to listen on.
--hoststring127.0.0.1Interface to bind. A non-loopback host requires OC_SERVER_PASSWORD.

See 07 · Headless and server.

oceancode acp

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

Serves the engine as an Agent Client Protocol agent over stdin/stdout, which is how Xcode and other ACP editors launch it. stdout carries only newline-delimited JSON-RPC; the banner, diagnostics and tracing go to stderr. There is no HTTP surface, and the command returns when the editor closes stdin. It takes only the common engine flags. See 20 · Xcode and other ACP editors.

oceancode workflow

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>]

run starts a host-run Rhai workflow and prints each workflow_updated body to stdout as one JSON line. The last line is the terminating body, and the command exits with the workflow/goal code above. Put the name or path first, then the flags. runs lists the persisted runs for the current project, newest first; it takes no --db or --verbose. pause and stop (run id first) act on a run that is live in the engine that same command boots. resume also resumes a run on disk (paused, budget-limited, or interrupted by a killed process), streams it like run and exits with the same codes (25 · Workflows).

FlagSub-subcommandsTypeDefaultMeaning
--argsrunstring{}JSON object bound to the workflow's args global.
--budgetrun, control verbsstringfrom configrun: absolute bound on cumulative child-agent calls, 1..=1024. resume: a higher call bound that lifts a budget-limited run.
--validate-onlyrunbooloffMetadata and compile check only; launches no agent.
--model, -mrunstringemptyprovider/model for steps that name no model. There is no default provider.
--allrunsbooloffList runs from every project.

See 07 · Headless and server.

oceancode goal

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

Launches the built-in goal workflow (Plan → Work → Verify) and prints each goal_updated body to stdout as one JSON line. It exits with the workflow/goal code above. The objective must be the first argument, with the flags after it. A missing objective, or a flag in first place, fails with missing objective: usage: oceancode goal "<objective>" [--budget <n>] [--model <provider/model>].

FlagTypeDefaultMeaning
--budgetstringfrom configAbsolute bound on cumulative child-agent calls for the goal, 1..=1024.
--model, -mstringemptyDefault model for every goal agent that names none. There is no default provider.

See 07 · Headless and server.

oceancode ledger

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

path prints the absolute ledger directory of the session. rebuild rebuilds the ledger mechanically and prints rebuilt <n> turn(s) in <dir>. --merge then prints the number of merge chunks and asks fold forward with model calls? [y/N] on stderr before folding them forward, which costs model calls. The session id is read after the flags, so write the flags first; a flag placed after the id is not applied. With the ledger disabled (ledger.enabled = false), rebuild fails.

FlagTypeDefaultMeaning
--mergebooloffrebuild only: fold the merge backlog forward after the rebuild (model calls).
--yesbooloffrebuild only: skip the y/N confirmation for --merge.

See 06 · Session ledger and export.

oceancode export

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

Writes a whole session as one Markdown document or as an ATIF-v1.8 trajectory (JSON). Pass exactly one of --md or --atif. As with ledger, the session id is read after the flags, so write the flags first.

FlagTypeDefaultMeaning
--mdbooloffWrite the session as one Markdown document.
--atifbooloffWrite the session as an ATIF-v1.8 trajectory (JSON).
--outstring-Output path; - writes to stdout.

See 06 · Session ledger and export.

oceancode login

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

Logs in to a provider and stores the credential in the data dir's auth.json. claude (the default; also anthropic, claude-pro, claude-max) runs the Claude Pro/Max OAuth flow: it prints the authorize URL and reads the pasted code from stdin. copilot (github-copilot) and codex (openai) run the OAuth 2.0 device-code flow and store the credential under github-copilot or openai.

FlagTypeDefaultMeaning
--providerstringclaudeProvider to log in to: claude, copilot or codex.
--no-browserbooloffPrint the authorize URL only; do not try to open a browser.

A --features platform build adds --provider ocean (alias plungeai: the PlungeAI account sign-in, OAuth 2.1 with PKCE at signin.plungeai.com, refresh token in the keychain item plungeai / oceancode), --key (with --provider ocean: the older dashboard sign-in that stores an ozk_ account key instead) and --sso-token <token> (stores a gateway SSO session token). See 15 · Platform mode.

oceancode slack

oceancode slack connect [--channel] [<C…|G…>]
oceancode slack status
oceancode slack on
oceancode slack off
oceancode slack disconnect

Pairs the engine's Slack bridge with one Slack app and one channel. connect reads SLACK_BOT_TOKEN (xoxb-…) and SLACK_APP_TOKEN (xapp-…) from the environment, else two lines piped on stdin (the bot token first), else asks for both in the terminal with echo off, so what you paste never shows. Every value is cleaned first: the terminal's paste markers and every character that is not a letter, digit or dash (spaces, quotes, a zero-width space) are removed. Only one of the two variables, or a single piped line, is refused with exit 2. A malformed token or channel id is refused before any network call, with a line that names the wrong one and what was given instead by its prefix and length (the first token is the app-level token (xapp-), the app-level token must start with xapp-; the second token given (21 characters) does not), never its text. It then calls auth.test (the bot token), conversations.info (a public channel is refused with exit 2: anyone in the workspace could run prompts on this Mac) and apps.connections.open (the app-level token and Socket Mode) and posts Ocean Code connected from <hostname> in the channel; only when all of them succeed does it store the tokens and the channel in auth.json and print SLACK_CONNECT_OK team=<team> channel=<id>. status prints team <team> · bot <user id> · channel <id> · slack <on|off> · OC_SLACK <on|off> from an auth.test with the stored token; it asks no engine. off turns Slack off for every window on this Mac, the open ones within two seconds, and prints slack: off (the tokens are kept; …); on turns it back on and prints slack: on; both write the file slack-off beside auth.json (or remove it) and keep the tokens. disconnect removes the stored entry and prints slack: disconnected, also when nothing was stored. No subcommand prints a token.

FlagSub-subcommandsTypeDefaultMeaning
--channelconnectstringthe stored channelThe channel's id, C… or G…; the id alone after connect means the same. Required on the first connect.
CodeMeaning
0Connected, the status printed, switched on or off, or disconnected.
1status, on or off found nothing stored: slack: not connected (oceancode slack connect --channel <id>).
2A usage error, missing or malformed tokens, no channel, a public channel, or Slack or auth.json refused; the message is on stderr.

See 24 · Slack.

oceancode logout

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

Removes one provider's stored credential from auth.json; the default is anthropic. Accepted names: anthropic/claude, zai-coding-plan/zai/glm/zai-coding/glmcoding, and ocean/plungeai. For ocean after an account sign-in it first revokes the sign-in at signin.plungeai.com, then deletes the keychain item and the auth.json entry (a failed revoke removes nothing). If nothing is stored, it prints No stored <provider> credential. and exits 0. Takes no flags.

oceancode key

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

Stores an API key in auth.json (type api). The provider defaults to anthropic and takes the same names as logout. With no key on the command line, the key is read from stdin when stdin or stdout is not a terminal; in a terminal, a non-Anthropic provider prompts for it. With no key at all, the command prints the credential status for anthropic and zai-coding-plan. A key without the expected sk-ant- prefix triggers a warning but is still stored. Takes no flags.

oceancode auth

oceancode auth

An interactive picker: 1 Anthropic API key, 2 Claude subscription (runs login), 3 GLM coding plan (runs key zai-coding-plan). Needs both stdin and stdout to be a terminal and fails otherwise. Takes no flags.

oceancode claude

oceancode claude

Checks the claude-code provider before you use it. It reports the claude binary's path (or claude.bin from config), its --version, and whether a Claude Code login is present. Advisory only: it exits 0 whatever it finds. Any argument fails with usage: oceancode claude.

oceancode inspect

oceancode inspect [--json]

Prints where every config key, skill, agent, command, MCP server and instruction file comes from, for the current directory (there are no --dir/--home flags). Each human row is kind id winning-layer source, and the last line is INSPECT_OK sources=<n>. With --json the JSON array goes to stdout and the sentinel to stderr. Boots nothing. See 09 · Capabilities and plugins.

oceancode plugin

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

--root (also --root=<home>) overrides the home that the stores live under (<home>/.oceancode/plugins and <home>/.oceancode/marketplaces).

Sub-subcommandPrints
marketplace add <spec> / update <n> / remove <n>PLUGIN marketplace-added|marketplace-updated|marketplace-removed <name>
marketplace list<name> plugins=<n> per marketplace
install <name-or-path> [--trust] [--marketplace <m>]PLUGIN installed <name> <version>, plus PLUGIN trusted <name> with --trust
list<name> <version> enabled=<bool> trusted=<bool> per plugin
uninstall <n> / update <n>PLUGIN uninstalled <n> / PLUGIN updated <n> <version>
enable <n> / disable <n>PLUGIN enabled|disabled <n>
enable-all / disable-allPLUGIN enabled-all|disabled-all count=<n>
trust <n> [--off]PLUGIN trusted|untrusted <n>
validate <n>PLUGIN validated <n> ok=<bool>, then one - <problem> line per problem
import --from claude-code [--trust] [--no-repo-trust] [--dry-run] [--home <h>] [--dir <d>]Ends with IMPORT_OK plugins=<n> marketplaces=<m> repo_trust=<bool> (IMPORT_DRY_RUN_OK … under --dry-run). import takes --home/--dir, not --root.

See 09 · Capabilities and plugins.

oceancode mcp

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

--root (or its alias --dir) selects the project directory where .mcp.json lives; the default is the current directory. --home selects the home tier.

Sub-subcommandBehaviour
add <name> --command <cmd> [--arg <a>]… [--env K=V]…Writes a stdio server to <dir>/.mcp.json under mcpServers.<name>. Prints MCP added <name> stdio.
add <name> --url <url> [--header K=V]…Writes a remote (type: http) server. Prints MCP added <name> remote. Pass exactly one of --command or --url.
remove <name>Deletes the entry from .mcp.json. Prints MCP removed <name>.
enable <name> / disable <name>Clears or sets the server's held-disabled bit in the trust store. Prints MCP_ENABLED/MCP_DISABLED <name>.
listOne row per discovered server: name stdio|remote tier trusted|untrusted enabled|disabled|shadowed source.
login <name> / logout <name>login prints the OAuth callback URL and contacts no network. logout clears the stored OAuth entry.
doctorConnects to each server with a 2-second budget and prints one status row per server (connected, needs-auth, failed, disabled, untrusted).

See 11 · MCP servers.

oceancode skill

oceancode skill [--root <dir>] [--dir <d>] [--home <h>] <subcommand>
Sub-subcommandBehaviour
create <name> [--description <text>]Writes <root>/.oceancode/skills/<name>/SKILL.md (--root defaults to the current directory) and prints SKILL created <path>. Refuses to overwrite an existing skill.
list [--json]One row per discovered skill: id tier trusted|untrusted state description. state is enabled or the reason the skill is disabled.
enable <id> / disable <id>Flips one skill's user-tier enable bit. <id> is a stable id, or a bare name that matches exactly one skill. Prints SKILL enabled|disabled <id>.
enable-all / disable-allPrints SKILL enabled-all / SKILL disabled-all count=<n>.

See 09 · Capabilities and plugins.

oceancode trust

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

Reads and sets the per-project trust record in <home>/.oceancode/trust.json. show prints repo=<bool>, then one mcp <name>=<bool> line per override and one disabled <name> line per held server. Every subcommand ends with TRUST_OK. repo grants or revokes repo-tier execution (repo hooks and .mcp.json servers). mcp sets a per-server override that takes precedence over repo, or clears it. See 11 · MCP servers.

oceancode hooks

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]

list prints every hook source file the boot loader reads: one line per source with its tier, its trust, whether it is loaded (or held, and why) and its path, followed by its handlers. The output ends with HOOKS_OK sources=<n> handlers=<m> loaded=<k>. --json prints {"repo_trusted", "sources"} and no sentinel. add and remove edit Claude Code's settings.json for the chosen scope (default project) and print HOOK_ADDED <path> or HOOK_REMOVED <path>. Removing a handler that does not exist fails with hooks remove: no such handler. See 10 · Hooks.

oceancode jev

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>

Inspects the Jev decision layer, read from the current directory and the environment (no --dir/--home flags). status prints one point mode endpoint-host line for each of the nine decision points — permission, output_view, supervisor, triage, visibility, check, guidance, snippets, effort — then JEV_STATUS_OK points=9; --json prints {points, endpoint, thresholds} instead, with JEV_STATUS_EMITTED points=9 on stderr. On a project with no jev section every point is off:

permission   off     -
output_view  off     -
…
effort       off     -
JEV_STATUS_OK points=9

probe makes one live call to Jev and prints JEV_PROBE_OK or JEV_PROBE_FAIL <why>; probe --record records a fixture. labels exports labelled decisions (JEV_LABELS_OK added=<n> total=<m>), each row's source telling a person's answer (shadow-user) from the labels the effort and snippets points write themselves (implicit-effort, implicit-snippets); --unlabelled requires --out. The tool_tiers and relevance points were retired on 2026-10-21 and no verb lists them. questions --json and verdicts --in print the decision points' question sets and policy verdicts for the bench. Only probe calls Jev. See 13 · Jev decisions.

oceancode doctor

oceancode doctor [--storage]

Reports orphaned sessions (registry entries whose process died without a clean exit) and captured panic reports found under the data dir. --storage adds the storage report: the sizes of oceancode.db and its WAL, the session count, and the ledger directory's size and oldest session age. Read-only; any other argument is ignored. See 18 · Operations.

oceancode peers

oceancode peers [log [--since <n>m|<n>h|<n>d]] [--data-dir <d>]
oceancode peers card [--since <n>m|<n>h|<n>d] [--data-dir <d>]

Lists the Ocean Code sessions running on this machine, read from the session line every engine joins (its record is <data dir>/line/messaging.db): each session's state (idle, working, blocked), title, directory and pid, what it is doing, and the files (or name:<label> work) it is writing. peers log prints the history, oldest first — who claimed, released, was blocked, overrode a claim, expired or changed_under another session, whose approved plan met another's (overlap), and every write with the lines it changed (wrote, the lines in parentheses); slots add deployed, deploy_refused, live_ok, live_failed, overwrote, check_failed, unprotected and slot_lost; lands add landed, land_refused and hold — for the last two hours, or --since (30m, 2h, 7d; the log keeps seven days). Each row starts with its date and time in UTC (2026-10-29T16:21:03Z). peers card (0.8.8.107) counts that log on one screen, for the last seven days or --since: sessions, claims, refusals and how long a refused session waited until it got the file, writes that passed unprotected, deploys, live checks and holds; then lands, lands applied on top of a branch that had moved, refused lands by reason, and the time from a refused land to the land that repaired it. --data-dir reads another data dir's line. The command changes nothing of its own: it joins the line while it runs, and hosts it when no other engine runs. See 12 · Session peers.

oceancode status

oceancode status [all | <code | words>] [--watch] [--data-dir <d>]

Prints the board of every Ocean Code session on this machine, read from the session line, sessions that wait for you first:

Ocean Code sessions · 2 · 1 working, 1 empty
#2oca  working         AI consulting v3  3/9  4m
       now: Task 16: round-2 re-review running
       next: Task 16 fix round 2 · 1 helper · holds 2 files · est. ~40m–1.5h (rough) · pid 45683
#f2k1  empty           New session  12m
       pid 51022

Each session has a code, the last four characters of its id (#2oca), and one state: waiting for you (a permission or a question is open), blocked (another session holds a file it needs), stuck? (working, but its plan has not moved for 30 minutes), working, idle, empty (a window nobody has typed into yet), done (idle with every plan row done), crashed or closed. The second line is the plan row in progress (or the running tool), the third the next row, the sub-agents it runs, the files it holds, a rough estimate (once three rows are done and the plan has not grown for 15 minutes: the pace so far, ×0.7–×1.5) and the window's pid. An at: line names the file and the lines the session last read or wrote (at: src/a.rs lines 120-134, relative to its folder). The board lists every open session, plus closed or crashed ones with open plan rows from the last three days (resume: oceancode resume <code>). all lists every session it knows (cards are kept 14 days); a code (2oca or #2oca, any case) or words from a title, a plan row or a folder list the matches. --watch reprints the board when the line reports a change, and every two seconds for its ages. A session opened by a build before 0.8.8.51 shows without its plan until that window is relaunched. The TUI's /status and the agent's sessions tool print the same board.

oceancode resume

oceancode resume [<code | words>] [--listen <addr>]

Opens any Ocean Code session on this machine, wherever it ran: the board knows each session's store and folder, so the TUI starts in that folder, on that store, with the session open and its resume card printed (19 · Ocean TUI). The query is a code (2oca, any case; quote '#2oca', since bash reads an unquoted # as a comment) or words from a title, a plan row or a folder. The global --data-dir reads another data dir's board and opens the TUI on it.

  • No query prints the board and Resume one with: oceancode resume <code>.
  • A session another Ocean Code window has open is not opened twice: the command names that window's pid and exits
    1. Switch to that window, or close it there first.
  • Several matches (two sessions whose ids end in the same four characters, or words that fit several) open nothing: the command prints them and exits 1.
  • No match on the board (a session opened by a build without cards) looks in this folder's store, as ocean-tui --resume <id or title> does.

oceancode workspace

oceancode workspace init ocean-git://<repo>@<ref> [dir] --handle <handle> [--sync]
oceancode workspace status
oceancode workspace land -m <message> [--branch <branch>]
oceancode workspace sync

An Ocean Git workspace is a plain folder that holds only the files the agent fetches from Ocean Git — no clone, no .git. workspace init resolves <ref> (a branch, tag or commit id; main when there is no @) to a full commit id and writes <dir>/.oceancode/ocean-git.json ({url, repo, ref, base, handle}); dir defaults to a new folder named after the repo in the current directory, and a folder that is not empty is refused. It prints WORKSPACE_INIT_OK dir=<dir> repo=<repo> ref=<ref> base=<sha>. The handle is --handle, else OC_OCEAN_GIT_HANDLE; the token is the macOS keychain item ocean-git/<handle>, else OC_OCEAN_GIT_TOKEN; the URL is OC_OCEAN_GIT_URL (default https://git.plungeai.com).

oceancode started in that folder (or below it; the TUI, acp and serve alike) reads the base commit through Ocean Git: read of a file not yet in the folder fetches it first, read of a folder and glob merge the commit's file list with the folder's own files, grep uses Ocean Git's search and re-searches the files changed in the folder (until the server has a search route it searches the folder only and says so), and the extra tool materialize {prefix?, glob?} fetches up to 2,000 files at once so bash can work on them. Files are kept in ~/.cache/oceancode/og/ ($XDG_CACHE_HOME/oceancode/og), checked against their blob id. A second extra tool, land {message, branch?}, commits the folder's changes (below). The system prompt gains one paragraph after the <env> block saying the folder is an Ocean Git workspace at <repo>@<ref> and its base commit, that read/glob/grep reach the whole repository, to run materialize before bash needs files, to commit with land, and never to git clone or git init there. Without the marker no tool and no prompt byte changes.

workspace status (inside a workspace) prints the base commit, then fetched=<n> modified=<n> new=<n> deleted=<n> and one line per changed path (M, A, D): a fetched file whose size and modification time are as fetched is unchanged, otherwise it is re-hashed; new is a file not in the base commit (.oceancode/, target/, node_modules/ and what the folder's .gitignore ignores are skipped); deleted is a fetched file that is gone.

workspace land -m <message> [--branch <branch>] (inside a workspace) commits those changes as one Ocean Git commit, built on the server (POST /api/commits): no git, no clone, no push. It is the land tool's code path without a model. A modified or new file is sent whole (UTF-8 as text, anything else base64; mode 100755 when executable, 120000 for a symlink, sent as its target), a deleted file as a delete; a move is a delete plus a new file. --branch defaults to the workspace's ref; it must be main or a branch of your own, <handle>/<name> (created when missing), and a workspace made from a branch other than main lands only onto that branch. Refused before anything is sent: no changes, more than 1,000 changes, a file over 8 MiB, a request over 32 MiB, another handle's branch.

When the branch moved since the base and touched other files, Ocean Git applies the changes on top of it (rebased=true); when it touched the same files, nothing lands, the conflicting paths and the branch's head are reported, and nothing in the folder changes (the folder still holds the base's versions of those files). After a land the marker's base is the new commit and its ref the branch, the landed files are recorded at their new blob ids, so workspace status shows modified=0 new=0 deleted=0; a fetched file you had not changed but the branch did between the old base and the new parent is removed from the folder (and read fetches the new version), while a file you had changed is never removed. It prints WORKSPACE_LAND_OK commit=<sha> branch=<b> rebased=<bool> files=<n> (and a summary on stderr), or WORKSPACE_LAND_FAIL <reason> and exits 1. In a repository whose .oceancode/ocean-hub.json says "guard": true the command sends nothing (0.8.8.108): the folder's copy, or since 0.8.8.110 the repository's own at the base commit, which a workspace does not fetch; a marker that cannot be read refuses too. Only a session can show what the guard asks (12). The land tool asks permission under the key land with the branch as the pattern (12 · Permissions).

workspace sync (0.8.8.107, inside a workspace) is the way on after such a refused land: it moves the base to the head of the workspace's branch and looks only at the files the branch changed since the old base. A fetched file you did not change is fetched again at the head. A file changed on the branch and in the folder keeps your version, and the report shows what the branch changed in it (up to 10 files, 20 lines each); land refuses until that file has been changed (writing the same bytes again does not count), so the branch's change is taken in by hand and never overwritten unseen. A fetched file you deleted that the branch changed is not deleted unseen either: land refuses until it has been read (which fetches the branch's version) and, if it should still go, deleted again. Everything else in the folder is untouched. The workspace's state and its marker are saved before any file is removed; if either cannot be saved, nothing changes and the workspace stays at its old base (0.8.8.108; in 0.8.8.107 a state that could not be saved was only a warning). A fetched copy that cannot be removed keeps the old base's version, and land refuses it until it is removed or fetched again; writing it again does not end the refusal (0.8.8.109). The land that follows names the files that were changed on both sides, in its question (merged) and in its result.

The agent gets this as a third tool, sync, only in a workspace made with --sync (the marker then holds "sync": true; add the key by hand to switch it on later). There the refused land says Run \sync`` and the workspace paragraph names it. Without the key the tools, the paragraph and the refusal are those of 0.8.8.106, and the command above still works for a person.

Since 0.8.8.109 an engine left open in the folder notices when another process moved the workspace's base: this command, oceancode workspace land, or another engine's land or sync. Before any fetch, land or sync it compares the marker on disk with the base it holds, and when the base moved, it refuses with the workspace's base moved to <commit> on disk and saves nothing. Start the engine again in that folder. (In 0.8.8.108 such an engine wrote its old state back over the command's.)

oceancode base

oceancode base list
oceancode base apply <file.yaml> [--db <id>] [--dry-run] [--allow-destructive]
oceancode base schema <db> | query <db> "<sql>" [--param <json>]… [--read] | usage <db> | events <db>
oceancode base tokens mint <db> --role read|write|admin | list <db> | revoke <db> <token_id>
oceancode base delete <db> --yes

Ocean Base databases from the terminal, one database per kind: database YAML. <db> is a 32-hex id or a name from list. Every command takes --json, and --format markdown|yaml|json asks the server for that shape (?format= on every call) and prints the answer as it came. Service OCEAN_BASE_URL (default https://base.plungeai.com); key OCEAN_API_KEY, else the ocean entry an ozk_ sign-in stores in auth.json — with only the browser sign-in stored it answers "no Ocean API key" (15 · Platform mode).

oceancode migrate

oceancode migrate [--db <path>]

Opens the database named by --db (default oceancode.db), migrates it to the current schema, prints opened and migrated <path>, and exits.

oceancode update

oceancode update [--self-test]

Updates itself to the newest release on the configured channel; OC_UPDATE_CHANNEL (stable/beta) overrides update.channel. Both oceancode and ocean-tui are verified first, swapped atomically, and rolled back together if a health check fails. Prints UPDATE_APPLIED from=<old> to=<new>, or oceancode <v> is already the newest <channel> release. --self-test exercises the swap and rollback offline on stub binaries and prints UPDATE_OK from=<old> to=<new> rollback_tested=1, then UPDATE_SELF_TEST_OK binaries=2. No other argument is recognised. See 17 · Distribution and updates.

oceancode verify-release

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

Verifies the artifact's minisign <artifact>.minisig signature without any external tool. --pubkey replaces the embedded release key; --sha256sums also checks the artifact's entry in that SHA256SUMS file. Prints VERIFY_RELEASE_OK file=<name>. See 17 · Distribution and updates.

oceancode uninstall

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

Removes the installed oceancode binary from OC_INSTALL_DIR (default ~/.local/bin). --purge also removes the app's config and data dirs, but never a project's .oceancode/oceancode.db. Unless --yes is given, it lists every path and asks you to type oceancode to confirm. --dry-run prints would remove: <path> lines and removes nothing. The last line is UNINSTALL_OK removed=<n>. See 17 · Distribution and updates.

See also