Agent SDK overview
@cohortapp/agent-sdk is the runtime for Cohort's AI colleagues. One agent is one dedicated Apple-silicon Mac mini running the framework 24/7 — polling for events, reasoning with Claude Code, executing work, and maintaining persistent memory across sessions. The agent talks to your Cohort workspace as its source of truth: it appears in the org chart, claims board work, sends messages, and holds a real workspace email address.
The SDK ships as an npm package with one CLI (installed as both cohort and maestro — they are the same binary) plus cohort-mcp, an MCP server that exposes the workspace tool surface to Claude sessions.
The model: framework vs agent repo
You install the SDK to scaffold an agent repository. The framework and the agent's own state are cleanly separated, so framework upgrades never overwrite the agent's identity or history.
| The package provides | The agent repo owns |
| --- | --- |
| scripts/ — poller, daemon, cadence bus, triggers, hooks, PDF and media generation | CLAUDE.md — the agent's behavioural charter |
| lib/ — shared primitives: org client, model router, send gate, secrets broker | config/agent.json — identity, the sole source of truth |
| agents/ — 34 specialist sub-agent definitions | config/*.yaml — org enrollment, contacts, priorities, routing |
| workflows/, schedules/, teams/ — cadence and coordination templates | .env — credentials, never committed |
| policies/ — action classification, information barriers, injection defence | knowledge/, memory/ — institutional memory |
| plugins/maestro-skills/, .claude/ — Claude Code skills, hooks, commands | state/, logs/, outputs/ — queues, audit trails, deliverables |
create copies the framework files into the agent repo (including lib/), so the running agent has no runtime dependency on a global SDK checkout. Upgrades re-copy framework files and never touch the right-hand column.
How an agent runs
Every agent operates in three concurrent modes:
- Reactive — a lightweight poller watches the connected channels (workspace messaging, email, Slack, calendar) and routes inbound events to the daemon for classification and response.
- Scheduled — daily, weekly, monthly and quarterly cadences fire via macOS launchd. Ticks flow through a local file-backed cadence bus and are serviced by one persistent daemon; lightweight ticks run inline without spawning a model session at all.
- Proactive — a backlog executor reads the queues on a fixed interval, picks the top actionable items, and spawns parallel sub-sessions to execute them.
A resource governor gates every spawn (ADMIT/QUEUE/DEFER) based on live memory and load, a rate guard and budget cap protect spend, and the only thing that permanently stops an agent is a human writing an .emergency-stop file.
How an agent connects to Cohort
The workspace at https://os.cohortapp.com is the org's coordination plane: registry and hierarchy, the work board, approvals, decision rights, the knowledge plane, and an encrypted credential vault. The agent holds exactly one org secret — a paired API key in config/org.yaml — and leases everything else short-lived:
- Provider model keys (DeepSeek, Moonshot, OpenAI, …) are set once at the org and leased per spawn — they never persist on the machine. See Pairing and credentials.
- The org connection is fail-open by design: an agent keeps running through a multi-day workspace outage. Cohort is a coordination plane, not the agent's runtime.
The framework engine is called Maestro; the product surface is Cohort. The CLI answers to both names, config lives under org.cohort keys, and environment variables use the COHORT_* prefix (a compatibility bridge keeps the older NEOLITH_* spellings working).