Documentation

How Cohort turns one objective into a reviewed, merged diff: the org model, the architecture, the loop, the full tool surface, configuration, and how to extend it without touching core.

$npm i -g @bhavya-dhoot/cohort

$cohort login

$cohort init

$cohort run "Build a small Node utility library: a config loader, an input validator, and a health-check handler."

Overview

What Cohort is, and why judgment stays with Claude Code while everything else is mechanics.

Cohort turns one objective into a completed, reviewed diff. Claude Code plays CEO, planner, and reviewer for the run: it analyzes the objective, designs the org and the task graph, and reviews the work that comes back. It never writes implementation code itself.

OpenCode workers are the implementation layer. Each one runs as a short-lived agent in its own isolated git worktree, holding a disjoint set of files, verified independently before its work is ever trusted.

The org hierarchy a run implies, CEO to engineering manager to domain leads to specialists to reviewers to integration, is generated per objective as a plan artifact, not a set of always-on manager processes. Cohort keeps exactly one live lead: Claude Code itself. Domain leads and reviewers materialize as scoped subagents only when a phase needs one.

Underneath, the platform is deterministic mechanics behind an 18-tool MCP surface: persistence, process control, verification, and budget guardrails. No hidden magic and no dynamic code execution, with disk-resident state that survives a crash.

Hierarchy is data

The org chart is a versioned plan artifact, inspected and approved by a human, not a standing process tree.

Disk is source of truth

Worker state, events, and cost figures are written to disk before they're considered real. A crash rebuilds from disk, never from memory.

Verification never trusts self-report

A worker's own completion message is a hint, never proof. Only independent verification against the real worktree diff can mark it verified.

Architecture

One objective flows through four layers: an orchestrator, a tool surface, isolated workers, and a review gate.

Claude Code drives the 18-tool MCP surface directly: spawning workers, polling state, and running independent verification. Each OpenCode worker runs in its own git worktree, so parallel batches execute with zero file conflicts by construction. Passing diffs go to dedicated read-only reviewers, whose verdicts gate the merge to the run's integration branch.

Behind that surface sit 16 core modules under packages/core/src/, each with a single responsibility: worktree lifecycle, the worker state machine, verification, budget guardrails, review-verdict storage, and more.

config worktree opencode-client worker events tasks budget verify checks plan memory specialist review report mcp

Read the full design

The loop

Every objective runs the same eight-step cycle until the task graph is done.

Analyze

Turn the objective into a brief.

Plan

Task DAG, contracts, and file-ownership partitions, gated by human plan approval.

Generate org / specialists

Org chart and .opencode/agent/*.md specialists for this objective only.

Batch spawn

DAG-ready, non-overlapping tasks dispatched as isolated workers.

Verify

Independent verification against the real worktree diff, never self-report.

Review

Org-assigned reviewers read the diff and record a verdict.

Integrate

Passing work merges to the integration branch in DAG order, a full regression gate, then human pre-merge review.

Replan

Blockers replan only the affected subtree, capped at two or three iterations.

Hitting the replan cap escalates to a human instead of looping forever.

The tool surface

18 MCP tools, grouped by what they drive. Judgment stays in Claude Code; every tool here is mechanics.

Worker lifecycle

Provision, monitor, and settle a single OpenCode worker.

spawn_worker worker_status list_workers stream_worker_log abort_worker collect_worker verify_worker finalize_worker

Pipeline

Plan, batch, integrate, and replan across the whole task DAG.

plan_submit next_batch batch_status integrate_batch run_check_suite replan_record

Memory

memory reads, writes, appends, or bundles shared cross-run project memory.

Specialist

specialist generates, retires, or lists the .opencode/agent/*.md files a plan needs.

Review verdict

review_verdict records or reads a reviewer's verdict; a non-pass verdict requires findings.

Run report

run_report renders the run's markdown and mermaid observability report from on-disk artifacts.

Configuration

Five shipped YAML files under config/, each overridable per project in .cohort/config/.

orchestrator.yaml

Budget caps, replan cap, human gates, worker concurrency and timeout.

models.yaml

Task-type to provider/model routing, and the soft-cap downgrade target.

agents.yaml

Specialist archetypes, the deny-floor default permission, max concurrent specialists.

memory.yaml

Store, retention, and the per-handoff context token cap.

providers.yaml

Provider definitions; only an env var name is stored, never a literal key.

A project overrides any of these under .cohort/config/. Objects deep-merge key by key over the shipped defaults; arrays and scalars replace outright.

.cohort/config/models.yaml

routing:
  default: "anthropic/claude-sonnet"
  implementation: "opencode/grok-code"
  search: "anthropic/claude-haiku"
downgrade_on_soft_cap: "small_model"
small_model: "anthropic/claude-haiku"

Extensibility

Five extension points change platform behavior without touching packages/core/src.

Custom check suites

orchestrator.yaml, key checks.suites, run by run_check_suite.

Custom memory sections

memory.yaml, key sections, read and written through the memory tool.

Custom reviewers

A markdown agent file at .opencode/agent/<id>.md; review_verdict accepts any path-safe reviewer id.

Alternate worker backends

Any client satisfying the OpencodeClient interface, injected via createAgenticMcpServer({ deps }).

New providers

providers.yaml, key providers; only the env var name is stored, never a literal key.

Non-goal: no dynamic loading of arbitrary user JavaScript. No extension point evaluates a project-supplied script at runtime: config and markdown are auditable without executing them, and the backend interface is type-checked at the call site.

Read the extension guide

The proof run

A real run, not a hermetic test: Claude as orchestrator, real MCP tools, real OpenCode workers, at $0.

Given the objective "Build a small Node utility library: a config loader, an input validator, and a health-check handler," the orchestrator generated a CEO, an engineering manager, three domain leads, and three specialists, then spawned three OpenCode workers in parallel, each isolated in its own git worktree, each owning exactly one file.

Three live reviewer subagents then read the real diffs and caught a genuine bug: two of the three modules came back as ESM in a CommonJS project, unloadable under require(). The reviewers blocked both and passed the one clean module. The gate held: the blocked work was replanned instead of force-merged, and run_report rendered the observability report below straight from the run's on-disk artifacts.

3 / 1 / 0 / 2Tasks: total / done / failed / pending

6 / 2Reviews: total / blocking

8m 57sDuration

$0.0000Committed cost

Read the full run