Canopy

Open-source workspace protocol and command center for AI agent systems. Build autonomous AI companies — not chatbots.

Canopy is a workspace protocol that turns folders of markdown into fully operational AI companies. Define agents, skills, teams, budgets, and governance in plain files — then connect any AI backend (Claude Code, OSA, Codex, Gemini, Cursor, Aider, Windsurf) and watch them work autonomously on heartbeat schedules.

The desktop command center gives you a native app to hire from 330+ agents, watch them collaborate in a pixel-art virtual office, monitor token costs in real-time, and intervene when needed.

Manage AI systems, not prompts.

---

Quick Start

# Install and launch in one command
curl -fsSL https://raw.githubusercontent.com/Miosa-osa/canopy/main/install.sh | bash

Installs prerequisites, clones the repo, sets up the database, and opens the app.

# Already cloned? Manual setup
cd canopy && make setup && make dev

# Just want the protocol? No app needed
cd canopy/operations/sales-engine
# Claude Code, Cursor, OSA, Codex — any agent reads SYSTEM.md and starts working

---

How It Works

| Step | What Happens | |------|-------------| | 01 | Pick a workspace: sales-engine/, dev-shop/, content-factory/, cognitive-os/, or build your own | | 02 | Connect your agent: Claude Code, OSA, Cursor, Codex, Gemini, Aider, Windsurf, or OpenClaw | | 03 | Run: agent reads SYSTEM.md, discovers skills and specialists, operates autonomously |

If it can read markdown, it's hired.

---

Architecture

Pick Workspace (sales-engine, dev-shop, content-factory, cognitive-os, custom)
        |
        v
Backend API  (Elixir + Phoenix on :9089)
        |-- 54 controllers, 56 schemas, 67 migrations, ~151 routes
        |-- Agent lifecycle (heartbeat, sessions, budgets, governance)
        |-- Workflow engine (7 step types, DAG execution, cron scheduling)
        |-- Dynamic dispatch (content-based adapter routing)
        |-- 5-layer org hierarchy (Company → Division → Department → Team → Agent)
        |
        v
Desktop Command Center  (SvelteKit 2 + Tauri 2 on :5200)
        |-- 56 pages, 20 component groups, 48 stores
        |-- Dashboard (KPIs, active agents, budget burn)
        |-- Virtual Office (pixel-art 2D + 3D team visualization)
        |-- Agent Roster (hire from 330+ agents across 19 categories)
        |-- Sessions (live chat, tool inspection, session chains)
        |-- Workflow Designer (multi-step DAG workflows)
        |-- Cost Console (per-agent token spend, budget enforcement)
        |-- Library & Marketplace (agents, skills, templates, companies)
        |-- Reports & Analytics (6 report types, scheduled generation)
        |-- Governance (approval gates, audit trail, access control)
        |
        v
Connected Agents (Claude Code, OSA, Cursor, Codex, Gemini, Aider, Windsurf, OpenClaw)

Stack

| Layer | Technology | |-------|-----------| | Backend | Elixir 1.15 + Phoenix 1.8.5 | | Database | PostgreSQL (67 migrations, 56 schemas) | | Frontend | SvelteKit 2 + Svelte 5 + Tauri 2 | | Auth | Guardian + JWT + Bcrypt | | Scheduler | Quantum | | Real-time | Phoenix PubSub + SSE | | Backend port | :9089 | | Desktop port | :5200 | | OSA port | :8089 |

---

Features

Workspace Protocol

The Canopy workspace is a folder of plain markdown files. No proprietary server, no lock-in. The directory structure is the architecture:

L0  SYSTEM.md + company.yaml          Always loaded (~2K tokens)
L1  agents/ + skills/                 On-demand (~2K tokens per item)
L2  reference/ + workflows/ + spec/   Deep context (full content, via search)
L3  engine/                           Invisible (0 tokens, powers skills)

SYSTEM.md is the entry point: identity, boot sequence, core loop, skills list, agents list, routing table, and handoff protocol — approximately 120 lines that define the entire operating system.

company.yaml carries mission, budget, governance rules, org chart, and goal hierarchy with evidence gates.

Progressive Disclosure

Every entity — agents, skills, teams, projects, tasks — exposes itself in three tiers. The agent requests only what it needs, when it needs it.

Tier 0 (Catalog)     Name + one-line description only. ~100 tokens per entity.
Tier 1 (Activation)  Full manifest body loaded on demand. ~2K tokens per entity.
Tier 2 (Full)        All referenced assets: scripts, linked docs, evidence schemas.

The catalog is always cheap. Full manifests cost only when actually used. This achieves 96% context reduction versus systems that load everything upfront.

Agent Hiring

Browse and hire from a library of 330+ pre-built agents across 19 categories — or define your own in a markdown file. Agents are behavioral templates, not binaries.

Each agent file defines role, tools, coordination rules, escalation path, and heartbeat behavior. One-click hire from the Command Center or drop the file into agents/.

Heartbeat Protocol

Agents wake on schedule, check for work, execute, and delegate autonomously. The heartbeat is a 9-step GenServer cycle with atomic checkout, governance gate checks, and session continuity:

Agent wakes (schedule, task assignment, or mention)
  -> Retrieves identity and role
  -> Checks governance gates (pending approvals block execution)
  -> Loads continuation context from previous session
  -> Resolves adapter (override → content router → agent default)
  -> Fetches assigned tasks (sorted by priority)
  -> Atomic checkout (prevents double-work)
  -> Executes via resolved adapter
  -> Comments on progress, delegates subtasks
  -> Compacts session (summary + handoff for next heartbeat)
  -> Sleeps until next heartbeat

Session Persistence & Continuity

Agents resume context across heartbeats instead of starting cold:

• Session chains — linked sessions with parent_session_id and sequence_number tracking full execution history
• Automatic compaction — after each heartbeat, the Compactor extracts structured facts (tools used, errors, outputs, decisions) into a summary
• Handoff generation — markdown handoff document with pending items, key decisions, blockers, and continuation state
• Cross-heartbeat injection — next heartbeat loads the previous session's handoff as context preamble
• Chain queries — GET /sessions/:id/chain returns full session lineage with cumulative token usage
• Manual compaction — POST /sessions/:id/compact triggers on-demand summarization

Multi-Agent Coordination

Tasks are the communication protocol. No agent-to-agent messaging required.

• Delegation — create a child task assigned to a report, with adapter-aware routing
• Status — modify task fields
• Escalation — traverse parent chain up to orchestrator
• Atomic checkout — only one agent works on a task at a time (409 = move on)

Task hierarchy: Initiatives → Projects → Milestones → Issues → Sub-issues. Every task traces back to a company goal.

Dynamic Adapter Dispatch

One orchestrator dispatches work to different runtimes based on task content. The dispatch router uses a three-tier priority waterfall:

1. Task adapter_override   (explicit per-task)
2. Content-based routing   (label + regex matching)
3. Agent default adapter   (fallback)

Content patterns route automatically:

/delegate "Write the API spec"    → Claude Code (deep reasoning)
/delegate "Refactor 50 files"     → Codex (bulk code changes)
/delegate "Analyze screenshots"   → Gemini (multimodal)
/delegate "Run test suite"        → Bash (shell process)
/delegate "Check production"      → HTTP (webhook)

The delegation system creates subtasks with automatic adapter selection, finding idle agents that match the inferred adapter type. Preview endpoint available at POST /dispatch/preview for dry-run routing.

Budget Enforcement

Three tiers — visibility, soft alert, hard ceiling:

| Threshold | Behavior | |-----------|---------| | Always | Dashboard shows spend per agent, task, project, goal | | 80% | Soft alert — agent warned to focus on critical tasks only | | 100% | Hard stop — auto-pause, approval required to resume |

Tracks tokens and dollars. Rollup at any level (agent, team, department, division, organization). Enforced at every execution boundary — scheduler, manual invoke, task checkout. ETS atomic counters for lock-free performance.

Governance Gates

Approval enforcement integrated into the controller pipeline:

• Spawn gate — agents cannot be created without approval (configurable per workspace)
• Delete gate — agent termination requires authorization
• Budget override gate — exceeding limits requires explicit approval
• Strategy gate — proposals require board review before execution
• Heartbeat blocking — agents with pending approvals are blocked from execution
• Auto-execution — approved actions replay automatically via the Executor
• Idempotent — duplicate pending approvals are deduplicated

Governance is a Phoenix plug (CanopyWeb.Plugs.Governance) that halts with HTTP 202 when an action requires approval. The workspace's governance config determines which actions need approval and which roles are auto-approved.

POST /spawn  →  Governance plug  →  Gate.check(:spawn_agent)
                                      |
                         requires_approval?  →  yes  →  202 {pending_approval}
                                             →  no   →  :allowed (continue)

Organizational Hierarchy

Five-layer structure with cascading budgets:

Organization (billing entity, governance config)
  └── Division (business unit, head agent, budget)
        └── Department (functional area, head agent, budget)
              └── Team (execution unit, manager agent, budget)
                    └── Agent