🌊 OCEAN

Multi-agent software engineering orchestrator for the CLI.

Ocean sits between you and your coding agents (Codex CLI, Claude CLI, Cursor). It turns plain-language product direction into a living team chat: capture intent, let the characters reason through value, dispatch the next build to a coding brain, show proof for taste, then wind down until the next interval.

reify@Reifs-MacBook-Pro my-repo % ocean
🌊 Ocean: Workspace: /Users/reify/projects/my-repo
🌊 Ocean: Codegen backend → cursor_handoff
🌊 Ocean: Hello — what are we building today?
🌊 Ocean: The crew will keep building at intervals. Jump in whenever you want.

Install

pip install ocean
ocean --help

Requires Python 3.11+. Codex CLI (npm install -g @openai/codex) or Claude CLI required for code generation.

How it works

Ocean is an orchestrator — it does not write code itself. The default path:

1. Binds the current repo to lightweight product doctrine (VISION.md, TASKS.md, docs/project.json)
2. Chats with a small fixed cast that has roles, history, stance, and semantic memory
3. Ranks candidate improvements by value, effort, risk, verification path, and token spend
4. Dispatches the selected job to your configured coding brain (Codex, Claude, Cursor handoff, or dry plan)
5. Records proposals, chat history, screenshots, verification notes, and the next round of work

The agent does the coding. Ocean handles what should happen next, why it matters, how the result gets checked, and when the loop should stop for the round.

Quick start

# Default: chat-first team room; background loop keeps building at intervals
ocean

# Interactive REPL (onboarding + commands, then loop on exit unless --no-loop)
ocean chat --repl

# Legacy full wizard (crew → plan → execute)
ocean chat --full

# Loop with a custom cadence
ocean loop --interval 300

Set OCEAN_STRICT_CODEX=1 to abort when the Codex exec probe fails; default is warn-and-continue. Use ocean chat --no-loop for setup only (no loop). Use ocean loop when you specifically want the worker without the chat room.

Token Budget

Ocean is designed to keep building until you stop it, but it paces itself against the key/project tier you give it. Set the provider's daily token limit from the provider dashboard, and Ocean uses 30% by default, split into hourly and per-round chunks:

OCEAN_GEMINI_TPD=240000 ocean loop
OCEAN_OPENAI_TPD=240000 ocean loop
OCEAN_CLAUDE_TPD=240000 ocean loop

You can change the operating fraction with OCEAN_TOKEN_BUDGET_FRACTION=0.5, or bypass provider math with OCEAN_TOKEN_BUDGET_PER_DAY / OCEAN_TOKEN_BUDGET_PER_HOUR. Without a numeric key-tier limit or a provider response that exposes one, Ocean will keep the loop alive but pause codegen rather than spend against an unknown budget.

In the REPL (ocean chat --repl or ocean chat-repl):

ocean> prd: build a task tracker CLI with add/list/done commands
✅ PRD updated (docs/prd.md)

ocean> plan
🌊 Ocean: Preparing project context…
✅ Plan ready.

ocean> build
🌊 Ocean: Dispatching to agent — building now…
🌊 Ocean: ✅ wrote task_tracker.py
✅ Build complete — 1 file(s) written.

ocean> crew
🕹️ Moroni
  · Phase 1: gather resources. Phase 2: secure interfaces. 🕹️
  · Skills — Vision synthesis, phased roadmaps, acceptance criteria …

ocean> exit

Commands

Command	What it does
ocean	Chat-first team room; background build loop runs at intervals
ocean chat	Same chat-first session as bare ocean
ocean chat --repl	Interactive REPL; loop after exit unless --no-loop
ocean chat --full	Legacy wizard: crew → clarify → plan → execute
ocean chat --no-loop	Setup only, no autonomous loop
ocean chat-repl	Standalone quick REPL with prd: / plan / build / crew
ocean loop	Autonomous worker only (interval from prefs / --interval)
ocean crew	Show each agent's skills and voicing
ocean clarify	Capture project intent, save docs/project.json
ocean doctor	Check Codex/Claude auth and environment
ocean onboard	First-run setup: venv + pip install + pytest
ocean mcp-server	Run Ocean as a stdio MCP server for Cursor/Codex

The crew

The chat-first product loop keeps a small fixed cast in .ocean/actors.json:

Agent	Role
Captain	Orchestrator — turns conversation into the smallest valuable next move
Scrooge	Impact and money — checks adoption, value, and monetization
Edna	UX and product feel — keeps setup, screens, and workflows understandable
Q	Builder — translates selected jobs into pragmatic code changes
Mario	Ship and verify — proves the work runs and can be handed off

The legacy ocean chat --full / planner path still uses the older specialist personas in docs/personas.yaml: Moroni, Q, Edna, Mario, and Tony.

Codegen backends

Set in docs/ocean_prefs.json or via OCEAN_CODEGEN_BACKEND:

Backend	How it works
codex	Calls codex exec directly (default when Codex is authed)
cursor_handoff	Writes docs/handoffs/ for Cursor Composer to pick up
openai_api	Calls OpenAI API directly (requires OPENAI_API_KEY)
dry_plan_only	Generates backlog/plan only, no code execution

MCP server

Ocean can run as an MCP server for Cursor or any MCP client:

ocean mcp-server

Exposes ocean_turn, ocean_next_action, ocean_record_feedback, ocean_bootstrap_doctrine, ocean_health, ocean_set_codegen_backend.

Project layout

docs/
  prd.md          — what to build (set via `prd:` in REPL)
  project.json    — clarified spec (name, kind, goals, vision)
  personas.yaml   — agent voices and skills
  plan.md         — generated backlog
  handoffs/       — Cursor handoff files (cursor_handoff mode)
logs/
  events-*.jsonl  — structured session events
ocean/
  cli.py          — all commands
  codex_exec.py   — Codex CLI dispatch
  persona.py      — voice loading from personas.yaml
  planner.py      — backlog generation and execution
  pty_harness.py  — PTY driver for integration tests

Testing

pytest tests/       # 70 tests, ~25s
ocean doctor        # environment + auth check

License

MIT