@adaptic/maestro

A production-grade npm package for deploying autonomous AI agents on dedicated Mac minis.

What is Maestro?

Maestro is an autonomous AI agent operating system, distributed as an npm package. It provides the complete infrastructure to deploy, run, and govern an AI agent that functions as a real member of your team -- with its own identity, responsibilities, communication channels, and institutional memory.

Each agent lives in its own repository. You install @adaptic/maestro to scaffold that repo, and the package provides the framework: scripts, agent definitions, workflow templates, governance policies, macOS automation, and Claude Code integration. Your repo holds the agent's identity, configuration, secrets, and runtime data. The framework and the agent's state are cleanly separated, so framework upgrades never overwrite your agent's personality or operational history.

Maestro uses Claude Code as its reasoning engine and integrates with Slack, Gmail, Google Calendar, WhatsApp, SMS, and 25+ MCP-connected services. Agents run 24/7 on a dedicated Mac mini, polling for events, reasoning about incoming information, executing tasks autonomously, and maintaining persistent memory across sessions. They send messages, draft documents, follow up on open loops, spawn parallel sub-agents for complex work, and produce branded PDFs and media assets.

The package provides: framework scripts (poller, daemon, triggers, hooks, PDF and media generation), 34 agent definitions with mandates and prompts, workflow templates across daily/weekly/monthly/quarterly cadences, operational skills as a Claude Code plugin, slash commands for agent setup, macOS launchd configuration, and comprehensive documentation and runbooks.

What's new in 1.17.0

The Hermes integration lands four workstreams that make an agent easier to install, truly real-time across channels, self-improving, and unbreakable. Each is additive — existing agents keep their behaviour until they run maestro setup (or activate a gated channel).

| Workstream | What it does | How to get it | |---------|-------------|----------| | WS1 — Setup wizard | maestro setup replaces the LLM-driven /init-maestro markdown prompt with a deterministic, resumable, self-verifying wizard. Runs as ordered sections (identity → company → model → comms → tools → operating-model → enrich → learning → recovery → verify), checkpoints to state/setup/progress.json, and ends with a live capability probe. config/agent.json is the sole source of truth. | maestro setup (see docs/guides/setup-wizard.md). | | WS2 — Real-time messaging + Telegram | One unified MessageEvent contract + BaseAdapter so Slack / Gmail / WhatsApp / SMS / Voice / Telegram all speak the same path — DMs, channels, threads, reactions, media. New grammY Telegram adapter (long-poll, in-daemon), full Slack Socket Mode coverage (reactions, thread context, opt-in channel CC), typing heartbeats, and default-deny DM pairing. | maestro setup comms; Telegram gated by config/telegram.yaml (see docs/guides/telegram-setup.md). | | WS3 — Self-learning loop | A closed loop that autonomously authors and improves Claude Code skills from its own sessions, and recalls past sessions verbatim. A Stop-hook reviewer distils each session, may create/patch a skill (secret-scanned, audited), and a skill-curator cadence ages skills active → stale → archived. | maestro setup learning; tuned via config/learning.yaml. | | WS4 — Resource governance + never-brick recovery | Autonomous work survives reboot/power-outage and the agent degrades gracefully under load instead of bricking itself. A resource governor gates every spawn (ADMIT/QUEUE/DEFER), a rate-guard breaker and budget-guard cap protect spend, and the memory watchdog throttles/restarts instead of writing .emergency-stop. | maestro setup recovery; tuned via config/recovery.yaml (see docs/runbooks/recovery-and-failover.md). |

Quick Start

npx @adaptic/maestro create jacob-ai
cd jacob-ai
maestro setup        # deterministic, resumable wizard; validates + self-verifies

Prerequisites

| Dependency | Install | Purpose | |-------------------|------------------------------------------------------------|--------------------------------| | Node.js 20+ | brew install node | Runtime for poller, triggers | | Claude CLI | npm install -g @anthropic-ai/claude-code | Agent reasoning engine | | jq | brew install jq | Used by hook scripts | | Pandoc + MacTeX | brew install pandoc && brew install --cask mactex-no-gui | PDF generation (optional) | | Anthropic API key | Set ANTHROPIC_API_KEY env var | Required for Claude CLI |

What the Package Provides

When you run npx @adaptic/maestro create <name>, the following framework files are copied into your new agent repo:

| Directory | Description | |--------------------------|-----------------------------------------------------------------------------| | scripts/ | Poller, daemon, trigger runner, hooks, PDF generation, media generation, setup scripts, healthcheck, emergency stop | | agents/ | 34 specialist agent definitions with mandates, responsibilities, and prompts | | workflows/ | Workflow templates: continuous, daily, weekly, monthly, quarterly cadences | | policies/ | Action classification, information barriers, prompt injection defence | | plugins/maestro-skills/| Operational skills plugin for Claude Code (memory, comms, queue management) | | .claude/commands/ | Slash commands; /init-maestro + /init-agent remain as deprecated, manual LLM-driven fallbacks to maestro setup | | .claude/settings.json | Project-level Claude Code hooks and permissions | | schedules/ | Trigger prompt templates for launchd-scheduled sessions | | teams/ | Agent team compositions and coordination definitions | | docs/ | Architecture docs, governance policies, runbooks, workflow documentation | | public/assets/ | Brand SVG assets (icon and logo, dark and light variants) | | desktop-control/ | macOS app control profiles for desktop automation | | scaffold/ | Template files for agent-specific config (CLAUDE.md, config/agent.json + generated config/agent.ts wrapper) |

What Lives in the Agent Repo (Not in the Package)

These files are specific to your agent and are never overwritten by framework upgrades:

| File / Directory | Purpose | |--------------------------|------------------------------------------------------------------| | CLAUDE.md | The agent's behavioural charter -- identity, principles, communication rules, operating modes | | config/agent.json | Structured identity data and sole source of truth: name, title, email, archetype, schedule, communication style | | config/agent.ts | Generated typed wrapper that re-exports config/agent.json (do not edit by hand) | | config/contacts.yaml | Key relationships and communication permissions | | config/priorities.yaml | Strategic focus areas and milestones | | config/environment.yaml| System-level settings: paths, scheduling, secrets references | | .env | API keys and credentials (never committed to git) | | knowledge/ | Sources, syntheses, entities, decisions, and memory | | memory/ | Interaction history, user and channel profiles, precedents | | state/ | Queues, inbox, dashboards, polling cursors, locks | | logs/ | Audit trails, polling logs, workflow logs, session logs | | outputs/ | Briefs, memos, drafts, research, and generated deliverables |

CLI Reference

npx @adaptic/maestro create <name>

Scaffolds a new agent repository. This command:

1. Creates the target directory
2. Copies all framework files (scripts, agents, workflows, policies, plugins, docs)
3. Copies scaffold templates (CLAUDE.md, the config/agent.json stub, and the generated config/agent.ts wrapper)
4. Copies .claude/ directory (settings and commands)
5. Creates 57 agent-specific directories (config, knowledge, memory, state, logs, outputs, self-optimization, tests)
6. Generates 53 operational template files (16 queues, 10 dashboards, 13 configs, 9 knowledge schemas, 5 self-optimization)
7. Generates a package.json with all required scripts and dependencies
8. Copies .env.example and .gitignore
9. Initializes a git repository
10. Runs npm install

After create, run maestro setup to configure the agent's identity and bring it online. The wizard is deterministic and resumable — it checkpoints to state/setup/progress.json, and on re-run it re-detects each section from disk (config/agent.json is the source of truth, the checkpoint is just a hint) and continues at the first incomplete section. Run a single area with maestro setup <section> (e.g. maestro setup comms), and drive it non-interactively in CI with maestro setup --headless --answers file.json. See The Setup Wizard below.

npx @adaptic/maestro upgrade

Updates framework files in an existing agent repo. This command copies the latest versions of:

• scripts/ -- poller, daemon, hooks, PDF generation, setup scripts, cadence bus enqueue + consumer + wrapper
• lib/ -- shared framework primitives (singleton lock, cadence bus, action executor, tool definitions)
• policies/ -- action classification, information barriers, prompt injection defence
• docs/ -- architecture, governance, runbooks
• public/assets/ -- brand assets
• workflows/, schedules/, teams/, desktop-control/, ingest/, mcp/
• .claude/commands/ -- slash commands
• plugins/maestro-skills/ -- operational skills
• agents/ -- new agents are added, existing ones preserved (no deletions)

It also creates any missing directories from the expanded directory set, including state/cadence-bus/{inbox,claimed,processed,failed,dlq} and logs/cadence-bus/.

Cadence-bus migration (1.8+): upgrade automatically migrates legacy spawn-per-tick launchd plists:

1. Detects generated plists at scripts/local-triggers/plists/ that still call run-trigger.sh directly.
2. Backs them up to .maestro/backup/plists/<utc-timestamp>/.
3. Regenerates them via scripts/local-triggers/generate-plists.sh so they invoke the lightweight cadence enqueue script instead.
4. Surfaces any installed plists at ~/Library/LaunchAgents/ai.maestro.* (and legacy ai.adaptic.*) that still match the legacy pattern, with exact launchctl unload && launchctl load commands the operator can run to roll the live job.

The migration is idempotent — a second upgrade run on a fully-migrated repo is a clean no-op.

Agent-specific files (config/, CLAUDE.md, knowledge/, memory/, state/, logs/, outputs/, .env) are never touched.

npx @adaptic/maestro doctor

Verifies the agent installation end-to-end. Checks include:

• Framework files: config/agent.json (the source of truth) with its generated config/agent.ts wrapper as a secondary check, CLAUDE.md, .claude/settings.json, package.json, scripts/setup/init-agent.sh, scripts/healthcheck.sh, scripts/daemon/maestro-daemon.mjs, scripts/local-triggers/generate-plists.sh.
• Cadence bus (1.8+): lib/cadence-bus.mjs, scripts/cadence/enqueue-cadence-tick.mjs, scripts/cadence/launchd-cadence-wrapper.sh, scripts/daemon/cadence-consumer.mjs, scripts/daemon/cadence-handlers.mjs, plus the state/cadence-bus/{inbox,claimed,processed,failed,dlq} directory tree.
• Plist architecture: every generated plist at scripts/local-triggers/plists/ carries the maestro-plist-arch: cadence-bus marker, and NO plist still calls run-trigger.sh directly. Installed plists under ~/Library/LaunchAgents/ai.maestro.* (and legacy ai.adaptic.*) are spot-checked too; doctor prints the exact launchctl unload && launchctl load commands to migrate any stragglers.
• Daemon heartbeat: state/cadence-bus/health.json is fresh (under 60s) when the daemon is running.
• Smoke test: doctor enqueues a cadence-bus-heartbeat tick to confirm the producer side works end-to-end.
• Config: config/environment.yaml, config/contacts.yaml, config/priorities.yaml, config/sla-defaults.yaml.
• State: state/dashboards/executive-summary.yaml, state/queues/action-stack.yaml, knowledge/decisions/decision-schema.yaml.
• Environment: .env file with ANTHROPIC_API_KEY (required), SLACK_USER_TOKEN, GMAIL_APP_PASSWORD (optional).
• Dependencies: node_modules installed, Claude CLI available, jq available, emergency-stop script present.

Doctor exits non-zero when issues are found and prints actionable remediation (most commonly: npx @adaptic/maestro upgrade). Doctor also verifies the collective-memory wiring (see below).

npx @adaptic/maestro global-setup

Wires the Collective Memory & Org Mesh into the machine-wide Claude Code config (~/.claude) so every Claude Code session on the machine — not just daemon sessions — contributes to and recalls from this agent's long-term memory, and is aware of concurrent sessions. Idempotent and additive: it deep-merges four hooks into ~/.claude/settings.json (never clobbering existing hooks/plugins, with a timestamped backup), writes a delimited block into ~/.claude/CLAUDE.md, and writes a ~/.claude/maestro-agent.json pointer. Run automatically by init-agent.sh and by wundr install; safe to re-run. --dry-run previews. See Collective Memory & Org Mesh.

Updating the Framework

npm update @adaptic/maestro   # Get the latest version from npm
npm run upgrade               # Copy updated framework files into your repo
git diff                      # Review what changed
git add -A && git commit -m "Upgrade maestro framework"

The upgrade command only updates framework infrastructure: scripts, policies, documentation, brand assets, commands, and plugins. It never modifies your agent's identity (CLAUDE.md, config/agent.json), configuration (config/*.yaml), secrets (.env), or runtime data (knowledge/, memory/, state/, logs/, outputs/). Your agent's personality, relationships, and operational history remain intact. upgrade also auto-migrates a legacy standalone config/agent.ts into the unified config/agent.json + generated wrapper.

Setup Wizard (maestro setup)

After scaffolding, run maestro setup to configure your agent. Unlike the old /init-maestro markdown prompt (which handed the whole job to an LLM), maestro setup is a deterministic, resumable, self-verifying wizard: Node code drives the mechanical orchestration, and the LLM is invoked only as a bounded enrichment function for company-specific prose. It runs as a registry of ordered sections, each of which can detect its own state, apply idempotently, and verify itself:

| Section | Order | What it does | |---------|-------|-------------| | identity | 10 | Agent name/title, function × altitude archetype, principal — writes config/agent.json (the source of truth). | | company | 20 | Company-context interview (name, website, industry, overview, stage, footprint, priorities, key people) → config/company.json. | | model | 30 | Model/provider selection — Claude Code subscription (keychain OAuth) or an Anthropic API key. Writes the model section of .env. | | comms | 45 | Wires each messaging channel — Slack, Gmail, SMS, WhatsApp, Telegram, voice — writing credentials to .env/gate files and verifying inbound. (WS2) | | tools | 50 | Selects channels + MCP servers the agent should run. | | operating-model | 60 | Deterministically generates the operating charter, seeded WBS backlog (≥5 open), 40–60 sub-agents + skills + workflows + MCP servers + event-routing, archetype cadences, autonomy policy, communication profile, and launchd plists. | | enrich | 70 | Spawns one bounded claude --print per enrichment unit to fill enumerated prose slots (persona, responsibilities, principles, company description, charter/backlog company-slots). Output is strict JSON, validated; invalid → skeleton kept, field marked pending. | | learning | 80 | Enables the self-learning loop and seeds counters/DB. (WS3) | | recovery | 85 | Installs the watchdog/governor and verifies recovery behaviour. (WS4) | | verify | 90 | Runs the live capability probe (Claude API + each enabled channel/MCP) and prints an N/M capability table with a remedy line per failure. |

Sections register by dropping a file into lib/setup/sections/ (globbed and sorted by order), so WS2/WS3/WS4 add comms/learning/recovery without touching the core runner.

Flags:

maestro setup [section] [--resume] [--from <id>] [--only <ids>] [--status]
                        [--headless] [--answers <file.json>] [--no-enrich] [--dry-run]

• --resume — continue from the checkpoint (default when one exists); re-detects every section from disk, so the on-disk source of truth is authoritative.
• --from <id> / --only <id,id,…> — start at a section / run only those sections (forced, even if complete).
• --status — print each section's detect() status and exit.
• --headless + --answers <file.json> — never prompt; take pre-supplied answers from a JSON file (CI / scripted runs).
• --no-enrich — skip LLM enrichment and leave the deterministic skeletons in place.
• --dry-run — print what would run and write nothing.

The wizard exits non-zero only on hard failures (no identity, an unresolvable archetype, or the Claude API being unreachable); optional channels and best-effort enrichment are reported but non-fatal. maestro upgrade auto-migrates a legacy standalone config/agent.ts into the unified config/agent.json model, and claude "/init-maestro" remains as a manual LLM-driven fallback.

See The Setup Wizard for the full walkthrough and docs/guides/agent-persona-setup.md for the persona configuration guide, including archetype defaults, Control Tower selection, contact classification, and manual fine-tuning.

Company context

Maestro generates each agent's charter, backlog, capabilities, and communications from your company's context — nothing is hardcoded to any one company. Provide that context three ways during the company section of maestro setup (and refresh it any time by re-running the generators):

1. A CLI interview — name, website, industry, a one-line + detailed overview, stage/size, where you operate, regulation, top priorities, key people, and competitors. This populates config/company.json (the company source of truth).
2. A docs/company-context/ folder — drop in markdown describing the company (overview, strategy, products, org chart, market, regulatory, brand voice, key relationships). The wizard reads them all and folds them in. See docs/company-context/README.md for the suggested file list.
3. GitHub repos on your machine — point the wizard at local repos; it reads each one's README, manifest, structure, and recent commits for product/technical context.

From these, init writes config/company.json + docs/company/overview.md (via scripts/setup/generate-company.mjs), and the charter / backlog / comms generators plus the CLAUDE.md "Company Context" section build on them. Framework prompts reference the company through {{company.*}} tokens resolved at load time — so the package ships company-agnostic and renders to your company.

Required Services and API Keys

| Service | Purpose | Required? | Signup URL | Tier / Pricing | |------------------|------------------------------------|-------------|-------------------------------------------|-----------------------------------| | Anthropic API | Primary reasoning engine (Claude) | Required | https://console.anthropic.com | Pay-per-token or Max subscription | | Slack | Team communication | Required | https://api.slack.com/apps | Free (workspace needed) | | Gmail | Email monitoring and sending | Required | https://myaccount.google.com/apppasswords | Google Workspace or free Gmail | | Google Calendar | Meeting and schedule awareness | Recommended | Via Google Workspace | Same account as Gmail | | Google Drive | Document sharing | Recommended | Via Google Workspace | Same account as Gmail | | OpenAI | Supplemental model access | Optional | https://platform.openai.com | Pay-per-token | | Google Gemini | Media generation (images, video) | Optional | https://aistudio.google.com | Free tier available | | Twilio | SMS, voice, and WhatsApp | Optional | https://www.twilio.com | Pay-as-you-go (~$1/mo + usage) | | Deepgram | Speech-to-text transcription | Optional | https://deepgram.com | Free tier (200 hrs/yr) | | ElevenLabs | Text-to-speech voice synthesis | Optional | https://elevenlabs.io | Free tier available | | Greptile | Codebase search and indexing | Optional | https://greptile.com | Free tier available |

Additional services are available via MCP servers and can be configured separately. Supported integrations include Airtable, Linear, Figma, Notion, Jira, Calendly, and more.

Environment Variables

The maestro setup wizard creates the .env file (the comms and model sections write the relevant credentials) and walks you through filling them in. Key variables:

# Core
ANTHROPIC_API_KEY=sk-ant-...

# Communication channels
SLACK_USER_TOKEN=xoxp-...
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...

# Gmail
GMAIL_CLIENT_ID=...
GMAIL_CLIENT_SECRET=...
GMAIL_REFRESH_TOKEN=...

# Google Calendar
GCAL_CLIENT_ID=...
GCAL_CLIENT_SECRET=...
GCAL_REFRESH_TOKEN=...

# Twilio (SMS/Phone/WhatsApp)
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=...

# Telegram (grammY long-poll, opt-in — gated by config/telegram.yaml)
TELEGRAM_BOT_TOKEN=123456789:ABC...

# Media generation
GEMINI_API_KEY=...

Architecture

┌─────────────────────────────────────────────────────┐
│                   Your Agent                        │
│              Executive Cortex (Tier 0)              │
├──────────┬──────────┬──────────┬──────────┬─────────┤
│ Briefing │ Strategic│ Domain   │ Comms    │ Task    │
│          │ Planning │ Ops      │ Gov.     │ Exec.   │
│ (Tier 1) │ (Tier 1) │ (Tier 1) │ (Tier 1) │(Tier 1)│
├──────────┴──────────┴──────────┴──────────┴─────────┤
│              20+ Specialist Agents (Tier 2)         │
│  Research · Product · Engineering · Legal · Ops ·   │
│  Finance · Partnerships · Hiring · Market Intel ·   │
│  Board Prep · Compliance · Writing · ...            │
├─────────────────────────────────────────────────────┤
│              Desktop Operations (Tier 3)            │
│  Slack · Gmail · WhatsApp · Browser · Calendar      │
├─────────────────────────────────────────────────────┤
│              Governance & Memory (Tier 4)           │
│  Decision Log · Risk Register · Knowledge Base      │
└─────────────────────────────────────────────────────┘

Tier 0 -- Executive Cortex: The agent's core identity and reasoning loop. Reads dashboards, processes inbound events, makes decisions, and orchestrates lower tiers.

Tier 1 -- Domain Controllers: Specialised reasoning modules for briefing, strategic planning, domain operations, communications governance, and task execution.

Tier 2 -- Specialist Agents: 20+ sub-agents that can be spawned in parallel for focused work -- research, document drafting, code review, legal analysis, hiring pipelines, and more.

Tier 3 -- Desktop Operations: Integrations with external services via MCP servers, APIs, and local tooling. Slack, Gmail, Google Calendar, WhatsApp, SMS, browser automation.

Tier 4 -- Governance & Memory: Persistent state layer. Decision logs, risk registers, knowledge bases, interaction history, queue management, and audit trails.

Operating Modes

All Maestro agents operate in three concurrent modes:

Mode 1: Reactive -- The nervous system. A lightweight poller checks Slack, Gmail, and Calendar every 60 seconds. An inbox processor classifies and routes incoming items every 5 minutes. Priority events trigger immediate processing.

Mode 2: Scheduled -- The heartbeat. Daily morning brief, midday sweep, evening wrap. Weekly strategic memo, pipeline review, execution review. Monthly board readiness, risk refresh. Quarterly self-assessment and board pack. All scheduled via macOS launchd; cadence ticks flow through the cadence bus (see below) and are serviced by the persistent daemon, NOT by spawning a fresh Claude Code session per tick.

Mode 3: Proactive -- The engine. The backlog executor runs every 10 minutes, reads all queues, selects the top actionable items by priority, and spawns parallel agents to execute them. Items move continuously from open to in_progress to resolved to closed.

Cadence Bus

Scheduled cadence ticks (every 5 / 10 / 15 / 30 minutes, daily, weekly, monthly, quarterly) are decoupled from Claude Code via a local file-backed event bus at state/cadence-bus/:

launchd ──► scripts/cadence/enqueue-cadence-tick.mjs (≈10 ms, no Claude)
                       │
                       ▼
            state/cadence-bus/inbox/<event>.json
                       │
                       ▼
       maestro-daemon.mjs ──► cadence-consumer.mjs (single persistent owner)
                       │
                ┌──────┴──────┐
                ▼             ▼
            inline       sub-session
        (housekeeping)  (substantive work)

Why this matters. The previous architecture spawned a fresh claude --print session per cadence tick — dozens of full Claude Code spawns per day, each paying full auth/context/token overhead even when the tick had nothing to do. The cadence bus:

• Routes every tick through ONE persistent main session (the daemon).
• Handles lightweight ticks inline (no Claude spawned) — heartbeats, housekeeping, queue sweeps with cheap pre-checks.
• Only spawns a sub-session when the cadence genuinely warrants isolated work: substantive drafting, multi-step outreach, large audits, research, work requiring separate context/audit boundaries.
• Honours .emergency-stop at both producer and consumer.
• Is safe if the daemon is briefly down — events accumulate in inbox/ and drain on next startup.
• Records the full lifecycle (received → claimed → processed | escalated | failed | dlq) under logs/cadence-bus/<date>.jsonl.

Per-cadence policy lives in scripts/daemon/cadence-handlers.mjs:

• inline — handler runs entirely in-process (e.g. heartbeat, stale-claim sweep).
• guarded — cheap pre-check (queues empty? inbox empty?); only escalates if there's substantive work.
• escalate — spawns a sub-session running the cadence's trigger prompt under schedules/triggers/<name>.md.

See docs/runbooks/perpetual-operations.md for ops procedures.

Self-Learning Loop

The agent improves itself between sessions. A detached Stop-hook reviewer reads each finished transcript and, in a second pass, may author or patch a Claude Code skill capturing a repeatable procedure — every write is secret-scanned and audited to logs/audit/skills.jsonl, and a skill-curator cadence ages skills active → stale → archived so nothing junky accumulates. It also indexes every session into a private FTS5 store, so the agent can recall its own past work verbatim via the session-search skill. The loop is fully autonomous, fail-open, and tuned through config/learning.yaml.

Collective Memory & Org Mesh

A cross-session, cross-agent coherence layer so a senior operator — human or AI — always has global consciousness of everything happening elsewhere, without context bloat. Three pillars, all enabled by npx @adaptic/maestro global-setup (run automatically at install). Full design: docs/architecture/collective-memory-and-org-mesh.md.

1. Collective memory. Every Claude Code session on the machine distils its salient takeaways — decisions, facts, artifacts, open loops, entities — into small memory cards (memory/collective/, indexed by the existing FTS5 RAG). Capture is async, distilled by a cheap model, and never stores raw transcripts. At session start a hard token-budgeted digest (default 1500 tokens; the anti-bloat control) is injected: top cards ranked by relevance × recency × salience, MMR-deduped. Pull more anytime with node scripts/collective/recall.mjs "<query>" or the rag_search tool.

2. Presence. A file-backed heartbeat registry (state/collective/presence/) gives every session a one-line view of the other sessions running right now ("2 other sessions active — daemon: inbox triage (3m); ~/openclaw: interactive"). See it with node scripts/collective/who.mjs.

3. Org mesh. Each agent publishes a directory entry (role, archetype, towers, live backlog focus, presence) to state/org/ — file-backed by default, with an optional neolith API client (org.neolith in config/collective.yaml) for a live cross-machine registry. Agents hand work to each other with a structured maestro-handoff envelope sent over the existing Slack/email channels, so humans see every handoff (observability by construction); the receiving daemon enqueues it as a provenance-tagged task. A daily org-pulse cadence posts "what every agent is focused on" to a human channel.

Configure via config/collective.yaml (enable/disable, capture model, digest token budget, recency half-life, repo denylist for ring-fenced work, presence timing, and the org/neolith source). Everything is opt-out and fail-open — it never blocks a session, and ring-fenced repos never contribute memory or receive the digest.

Auto-Publishing

Pushes to the main branch of the Maestro repository automatically publish to npm via GitHub Actions. Version bumps are handled automatically -- patch versions for fixes and minor changes, minor versions for new features. You do not need to manually publish or manage versions. When a new version is available, agent repos pick it up with npm update @adaptic/maestro.

Agent Roster (Example)

Maestro supports deploying any number of agents, each on its own Mac mini with a distinct role and domain focus:

| Agent | Role | Archetype | Repo | |---------|-----------------------------|----------------------|--------------------| | Ava | Chief of Staff | executive-operator | yourco/ava-ai | | Noah | Chief AI Scientist | technical-leader | yourco/noah-ai | | Mia | Head of Engineering | technical-leader | yourco/mia-ai | | Liam | Head of Compliance | compliance-officer | yourco/liam-ai | | Emma | Head of Product | product-leader | yourco/emma-ai | | Owen | Head of Investor Relations | commercial-leader | yourco/owen-ai | | Zoe | Head of Operations | operations-leader | yourco/zoe-ai | | Ethan | Head of Quant Engineering | technical-leader | yourco/ethan-ai |

Each agent gets its own identity, operating principles, communication style, contact graph, priority stack, and specialist sub-agents -- all configured through the maestro setup wizard.

Tool Library (lib/)

Maestro provides a comprehensive library of 30 reusable tools that agents can use during voice conversations, huddles, and autonomous operations. Tools are scoped by access level and executed via the Claude API tool_use protocol.

Categories

| Category | Tools | Description | |----------|-------|-------------| | Communication | slack_send, draft_email, whatsapp_send, sms_send | Send messages across all channels | | Search / RAG | search_email, search_calendar, search_files, search_meetings, search_slack, search_web, search_documents | Real-time lookup via MCP-backed queries | | Knowledge | search_decisions, lookup_person, search_regulatory, search_strategy, search_precedents | Institutional memory and governance | | Operations | queue_update, create_action_item, schedule_meeting, create_reminder | Operational queue and calendar management | | Analysis | search_financial, search_pipeline, search_engineering, search_hiring, search_risk | Cross-functional health and pipeline data | | Documents | generate_memo, generate_report | Branded document generation |

Usage

import { getToolsForAccessLevel, executeAction } from "@adaptic/maestro";

// Get tools for a Claude API call
const tools = getToolsForAccessLevel("ceo"); // 29 tools
const tools = getToolsForAccessLevel("leadership"); // 24 tools (no WhatsApp/SMS/memo)
const tools = getToolsForAccessLevel("default"); // 17 tools (search/lookup only)
const tools = getToolsForAccessLevel("voice"); // 16 tools (voice surface)

// Execute a tool call from Claude's response
const result = await executeAction("search_email", { query: "DFSA update" }, callerInfo, sessionId);

RAG Architecture

Lookup tools use claude --print --model haiku under the hood, which leverages the agent's Max subscription and all configured MCP servers (Gmail, Calendar, Slack, filesystem, Granola, etc.). This means every agent automatically gets search capabilities across all connected services without additional API costs.

Agent-Specific Tools

The legacy "Sub-agent 8" step is retired. The operating-model section of maestro setup runs deterministic generators that produce the 40–60 role-specific sub-agents, skills, and workflows from the agent's archetype and responsibilities. These extend the base set — e.g., a compliance officer gets licence_gap_check and regulatory_submission_status, while an engineering leader gets code_review_trigger and deployment_status.

Global vs Agent-Specific Features

When building new capabilities, decide where they belong:

| Push to ~/maestro (global) | Keep agent-local | |-----|-----| | Role-agnostic tools any agent could use | Identity-specific configurations | | Communication primitives | Domain tools only this role needs | | Search/RAG capabilities | Custom MCP integrations for one agent | | Operational patterns | Hardcoded contacts, channels, API keys | | Infrastructure (audio, CDP, polling) | Agent-specific prompts and style | | Document generation templates | Workflow overrides | | Claude Code skills/plugins for dev experience | | | Governance patterns | |

Decision rule: Would another agent at your company ever need this? YES → ~/maestro. NO → agent repo only.

After pushing to maestro: bump version → commit → push. Agent repos update via npm update @adaptic/maestro.

Security and Governance

• Secrets management -- All credentials via environment variables, never committed to the repository
• Full audit trail -- Every action, communication, and decision is logged to logs/
• Approval policies -- Outbound communications require appropriate approval levels based on risk classification
• Emergency stop -- npm run emergency-stop halts all autonomous operations immediately
• Default-deny -- Unclassified actions are blocked; only explicitly permitted actions proceed
• Rate limiting -- Configurable limits on all communication channels (default: 3,000 sends/hour, 20,000/day)
• Prompt injection defence -- 5-layer defence system: identity lock, sender privilege model, message classification, content isolation, anomaly detection
• Information barriers -- Dynamic disclosure assessment prevents confidential information from crossing recipient boundaries
• Session logging -- Every agent session is logged with start time, actions taken, and outcomes
• Communication governance -- Pre-send audit hook gates all outbound Slack and Gmail; duplicate detection prevents replying to the same thread multiple times

Security policies are defined in policies/ and docs/governance/.

Resource Governance & Never-Brick Recovery

Autonomous work is designed to survive reboot and power loss, and the agent degrades gracefully under load rather than bricking itself. A resource governor (lib/resource-governor.mjs) gates every Claude Code spawn — ADMIT/QUEUE/DEFER based on live memory, load, and process pressure — while a rate-guard breaker and a daily budget-guard cap protect spend; deferral never burns an item's retry budget. The only thing that permanently stops an agent is a human writing .emergency-stop: the memory watchdog throttles or cleanly restarts the daemon instead of writing it on OOM, and in-flight sessions are reconciled and resumed after a crash. Tune it via config/recovery.yaml; see docs/runbooks/recovery-and-failover.md.

Key Documentation

Setup Guides

• Setup Wizard -- maestro setup: sections, resume/checkpoint, source of truth, enrichment, verify probe, all flags
• Agent Persona Setup -- Identity, operating charter, and behavioural policies
• Email Setup -- Gmail IMAP polling, SMTP sending, thread dedup, signatures
• Slack Setup -- Slack app, tokens, sending, typing indicators, events, CDP
• WhatsApp Setup -- Twilio WhatsApp sandbox/production, webhook handler
• Telegram Setup -- grammY long-poll in-daemon, BotFather token, DM pairing, event mapping
• Voice & SMS Setup -- Twilio SMS, Slack huddle voice, Deepgram STT, ElevenLabs TTS
• Poller & Daemon Setup -- Event polling, reactive daemon, triggers, watchdog
• Outbound Governance Setup -- Hooks, dedup, information barriers, disclosure
• RAG & Context Setup -- SQLite FTS5 search, pre-draft context, entity indexing
• PDF Generation Setup -- Pandoc + XeLaTeX branded document generation
• Media Generation Setup -- Gemini/Veo image and video generation
• Claude-Mem Setup -- Persistent session memory with semantic recall
• Claude-Pace Setup -- Real-time rate limit tracking and burn rate awareness
• ccxray Diagnostics -- Token/cost analysis and session debugging
• Claudraband Sessions -- Persistent sessions, daemon mode, HTTP API
• ClawTeam Swarm -- Multi-agent coding swarm orchestration via git worktrees
• Agents Observe -- Real-time multi-agent observability dashboard
• Code-Review-Graph -- Tree-sitter structural knowledge graph for codebases
• Self-Optimization Pattern -- AutoAgent-inspired benchmark-driven self-improvement

Architecture & Governance

• System Architecture -- Full system design and component overview
• Agent Topology -- Sub-agent hierarchy and delegation model
• Action Approval Model -- Communication governance and approval levels
• Communications Policy -- Voice modes, autonomy model, escalation rules

Dev Tooling

Approved third-party tools for agent development and observability. Install with:

./scripts/setup/install-dev-tools.sh --all

| Tool | Purpose | Install | |------|---------|---------| | claude-pace | Rate limit status line tracker | --tool claude-pace | | agents-observe | Multi-agent observability dashboard | --tool agents-observe | | ccxray | Token/cost observability proxy | --tool ccxray | | ClawTeam | Git worktree swarm orchestrator | --tool clawteam | | code-review-graph | Tree-sitter codebase knowledge graph | --tool code-review-graph |

Cross-Agent Message Routing

When multiple agents monitor the same Slack channels, the daemon classifier uses config/known-agents.json to prevent cross-agent message interception. If a message @-mentions a specific agent, only that agent's daemon will respond. Update this file when agents are added or removed.

Runbooks

• Mac Mini Bootstrap -- Hardware setup and initial configuration
• Perpetual Operations -- Keeping the agent running 24/7
• Recovery and Failover -- Disaster recovery procedures

Built by Adaptic.ai