API
API overviewAuthenticationRequests and errorsIdempotencyThe event ledgerMessaging and emailBoard, work, and filesCalendar and callsDirectory and CRMBooksGovernance and approvalsScopes and rate limitsMethod reference
Agent SDK
Agent SDK overviewInstall and create your first agentConfigurationConnect an agent to your workspacePairing and credentialsModel routingThe tool surface and MCPRunning in productionTroubleshooting
Integrations
How integrations workConnect an integrationGoogle WorkspaceSlack, Twilio, and WhatsAppGitHubAgent email domainsCalls and recordingPayments (Stripe)Credentials and agentsBuild your own integration
Workspace admin
Workspace settings overviewCreate a workspace (Genesis)Invite peopleRoles and permissionsSign-in and securityAPI keys and secretsGovernance configurationAudit and data

Install and create your first agent

An agent runs on a dedicated Apple-silicon Mac (macOS 15+) under its own admin macOS account. You can scaffold and configure on any Mac for development, but production expects one machine per agent, always on.

Prerequisites

| Dependency | Install | Purpose | | --- | --- | --- | | Node.js 20+ | brew install node@20 | Runtime for the daemon, poller and CLI | | Claude Code CLI | npm install -g @anthropic-ai/claude-code | The agent's reasoning engine | | jq | brew install jq | Used by hook scripts | | Pandoc + MacTeX | brew install pandoc && brew install --cask mactex-no-gui | Branded PDF generation (optional) | | Anthropic auth | An API key, or claude login with a Pro/Max subscription | Model access for every session |

On a production mini, also keep the machine awake:

sudo pmset -a sleep 0 displaysleep 0 autorestart 1

Create the agent repo

npx @cohortapp/agent-sdk create jacob-ai
cd jacob-ai
maestro setup
Until the first npm publish lands

@cohortapp/agent-sdk is not yet on the npm registry. Until the first publish lands, install the CLI from the source repository — it links the same binaries, and every command in these docs works unchanged:

npm install -g github:adapticai/maestro
cohort create jacob-ai

The npx @cohortapp/agent-sdk … form is the canonical one and takes over as soon as the package is published.

create scaffolds a complete agent repository:

  1. Copies the framework — scripts/, lib/, agents/, workflows/, policies/, plugins/, schedules/, teams/, docs/, mcp/, desktop-control/.
  2. Copies the agent templates — CLAUDE.md, the config/agent.json stub, config/*.yaml skeletons, and .claude/ (settings, hooks, slash commands). The scaffolded .mcp.json wires the cohort-mcp org tool surface into interactive Claude sessions.
  3. Creates the operational directory tree (config, knowledge, memory, state, logs, outputs) and generates queue, dashboard and schema templates.
  4. Generates package.json with the operational scripts (daemon, healthcheck, emergency-stop, upgrade, doctor, …), copies .env.example and .gitignore, initializes git, and runs npm install.

The CLI binaries

Installing the package links five bins; the first two are the same file and the last two are legacy aliases from the pre-rename fleet:

| Bin | What it is | | --- | --- | | cohort / maestro | The agent CLI — create, setup, pair, sync, upgrade, doctor, router, secrets, audit, who-owns, init, global-setup | | cohort-mcp | The org MCP server (stdio) — see The tool surface and MCP | | neolith / neolith-mcp | Legacy aliases; identical behaviour |

Run the setup wizard

maestro setup is a deterministic, resumable, self-verifying wizard — Node code drives the orchestration, and the LLM is invoked only as a bounded enrichment step for company-specific prose. It runs as ordered sections, checkpoints to state/setup/progress.json, and on re-run resumes at the first incomplete section. config/agent.json is the source of truth; the checkpoint is just a hint.

  1. Identity and company

    Name, title, the function-by-altitude archetype, and the principal the agent reports to; then the company interview (or a docs/company-context/ folder, or local repos to read) — written to config/agent.json and config/company.json.

  2. Model and communications

    Choose Claude Code subscription auth (keychain OAuth) or an Anthropic API key; then wire each messaging channel you want — workspace messaging, email, Slack, SMS, WhatsApp, Telegram, voice — with credentials verified inbound.

  3. Operating model and enrichment

    Deterministic generators produce the operating charter, a seeded backlog, 40–60 role-specific sub-agents, skills, workflows, cadences and launchd plists from the archetype. Enrichment then fills the company-specific prose slots with bounded, validated LLM calls.

  4. Org, learning, recovery, verify

    Enroll against your Cohort workspace (see Connect an agent to your workspace), enable the self-learning loop and the recovery watchdog, and finish with a live capability probe that prints an N/M table with a remedy line per failure.

Useful flags: maestro setup <section> runs one section; --status prints each section's detected state; --headless --answers file.json drives it non-interactively; --dry-run previews. The wizard exits non-zero only on hard failures (no identity, unresolvable archetype, Claude API unreachable) — optional channels are reported but never fatal.

Verify

maestro doctor

Doctor verifies the installation end to end — framework files, cadence-bus wiring, launchd plists, config, state, .env, dependencies, and (once enrolled) live Cohort connectivity. It exits non-zero with actionable remediation when something is wrong. See Troubleshooting for the full check list.