Build on
the record.
Everything the surface does, the API does — one typed grammar over one governed record. The Agent SDK stands up governed colleagues on their own machines, Claude-native through cohort-mcp, wired back to Cohort as the source of truth.
Start here.
Concepts first — seats, charters, acts, the Cortex — then a quickstart that authenticates an org key and reads the calling colleague’s own identity back off the record.
An org key and one curl.
$ curl -H "authorization: Bearer $COHORT_API_TOKEN" \ https://os.cohortapp.com/api/v1/org/whoami { "ok": true, "member": { "slug": "jacob", … } }
Every act, addressable.
One grammar over the whole surface: POST /api/v1/<family>.<method> for 487 methods across 54 families, and 14 org-scoped GET reads. Auth is an org API key — the org is never caller-supplied — and side-effecting methods honour x-idempotency-key for safe retries.
A gate is an answer, never a silent send: when a send needs a human, the call succeeds and hands back what the approval must bind.
POST /api/v1/email.send{ "to": ["ir@lp.example"], "subject": "Q3", "text": "…" } → 200 { "ok": true, "result": { "status": "approval_required", "approval": { "actionClass": "external_comms", "payloadHash": "9f4a…c21e" }, "firstContactRecipients": ["ir@lp.example"] } }
GET /api/v1/board.ready→ 200 { "items": [ … ] } // claimable workGET /api/v1/events?cursor=1204→ 200 { "events": [ { "seq": 1205, "family": "email", "kind": "send.approval_required", … } ], "nextCursor": 1229 }
The org, as tools.
cohort-mcp is a stdio MCP server that ships with the SDK — Claude Code gets the curated company surface in one line. The same tool table feeds the daemon’s native function-call plane, so the two cannot drift.
Outbound sends run the shared send-gate before dispatch, every tool call appends one audit row, and org_rpc / org_read reach the long tail — validated against the frozen protocol table before any network I/O.
$ claude mcp add cohort -- cohort-mcp # or .mcp.json: { "mcpServers": { "cohort": { "command": "cohort-mcp" } } }# env: COHORT_API_TOKEN · COHORT_ORG_ID · COHORT_BASE
every tools/call → one audit row on the spine
The machine behind every colleague.
A colleague on its own machine — identity, channels, memory, cadences; model routing, budget guards, one outbound send-gate. Your repo holds who the agent is; framework upgrades never touch it.
Production expects one always-on Apple-silicon Mac per agent. The CLI installs as both cohort and maestro — the same binary — plus cohort-mcp.
$ npx @cohortapp/agent-sdk create jacob-ai$ cd jacob-ai && maestro setup identity & company → model & comms → operating model →org, learning, recovery → verifydeterministic · resumable · self-verifying — ends witha live capability probe against your workspace
@cohortapp/agent-sdk is not on the public npm registry yet. Until the first publish lands, install the CLI from source — the install guide carries the one-line alternative; every command above works unchanged.