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 (individual worker, budget)

Full CRUD at every level. GET /hierarchy?organization_id=X returns the complete tree assembled from flat queries. Team memberships tracked via join table with role assignment.

Workflow Engine

DAG-based workflow execution with 7 step types:

Step Type	Description
agent_task	Assign work to a specific agent
approval	Block until human approves
condition	Branch based on previous step output
transform	Reshape data between steps
webhook	Call external HTTP endpoint
delay	Wait for specified duration
parallel	Execute multiple steps concurrently

Workflows support:

• Topological sort for dependency resolution
• Retry with configurable backoff (constant, linear, exponential)
• Cron-based scheduled execution via Canopy.Workflows.Scheduler
• Step-level status tracking (pending → running → completed/failed/skipped)
• OTP supervision for fault tolerance

Agent Commerce (Planned — requires Stripe MPP integration)

Agents will be able to buy things. Stripe's Machine Payments Protocol (MPP) lets agents transact autonomously — pay for APIs, buy compute, purchase services from other agent workspaces.

Canopy's budget enforcement will wrap around MPP:

• Under threshold — agent pays autonomously, logged to budget
• Over threshold — payment queued for human approval
• Over budget — hard stop, no payment authorized

---

Desktop Command Center

56 pages organized into functional clusters:

Cluster	Pages
Daily	Dashboard, Inbox, Chat, Virtual Office
Work	Issues, Projects, Goals, Work Products, Workflows
Agents	Agent Roster, Agent Detail, Spawn, Sessions, Schedules
Data	Memory, Documents, Datasets, Signals, Templates
Observe	Activity, Logs, Analytics, Costs, Reports, Alerts, Audit
Automate	Skills, Integrations, Webhooks, Plugins, Gateways
Library	Agent Marketplace, Skills, Companies, Teams (with detail pages)
System	Organizations, Hierarchy, Divisions, Departments, Teams, Users, Access, Config, Secrets, Environment

Virtual Office

Pixel-art 2D grid view and optional 3D scene (Three.js via Threlte) showing agents at desks. Agents glow when active, bob when working, and display current task in a speech bubble. Click to inspect or intervene.

Mock-First Development

57 mock API modules provide complete frontend functionality without a backend connection. Every API endpoint has a corresponding mock handler with realistic data, enabling offline development and demo mode.

---

Workspace Protocol

File Structure

A complete workspace — using the B2B sales engine as example:

sales-engine/
|
|  L0 — ALWAYS LOADED
|
+-- SYSTEM.md                 Entry point: identity, boot sequence, core loop,
|                             skills list, agents list, routing table
|
+-- company.yaml              Mission, budget ($5K/mo), governance rules,
|                             org chart, goal hierarchy with evidence gates
|
|  L1 — LOADED ON DEMAND
|
+-- agents/
|   +-- director.md           Pipeline review, deal strategy, forecasting
|   +-- prospector.md         Lead generation, ICP matching, outbound sequences
|   +-- closer.md             Discovery calls, demos, negotiation, close
|   +-- researcher.md         Market intel, competitive analysis, account research
|   +-- copywriter.md         Email sequences, proposals, case studies
|
+-- skills/
|   +-- prospect/SKILL.md    /prospect — find and qualify leads
|   +-- pipeline/SKILL.md    /pipeline — view pipeline status, forecasting
|   +-- qualify/SKILL.md     /qualify — run MEDDPICC qualification
|   +-- close-plan/SKILL.md  /close-plan — build deal close strategy
|   +-- battlecard/SKILL.md  /battlecard — competitive intel for a deal
|
|  L2 — DEEP CONTEXT
|
+-- reference/
|   +-- icp.md                Ideal customer profile, scoring rubric
|   +-- meddpicc.md           Full qualification methodology
|   +-- objections.md         20+ objections with response scripts
|   +-- sequences.md          Email templates with A/B variants
|
+-- workflows/
|   +-- deal-cycle.md         7 phases: Research -> Outreach -> Discovery ->
|                             Demo -> Proposal -> Negotiate -> Close
|
+-- handoffs/
|   +-- standard.md           Task clarity, constraints, expected genre
|   +-- escalation.md         When to escalate, who to, with what evidence
|
+-- spec/
|   +-- PROCEDURES.md         Action bindings with typed parameters
|   +-- WORKFLOW.md           FSM: lead states, deal states, triggers
|   +-- contracts/
|       +-- workspace.spec.md Self-validation and drift detection
|
+-- teams/
|   +-- outbound/TEAM.md      Members, shared budget, coordination rules
|
+-- projects/
|   +-- q2-pipeline/PROJECT.md Goals, milestones, budget envelope, assigned teams
|
+-- tasks/
|   +-- qualify-lead/TASK.md  Schedule, evidence gates, default assignee
|
|  L3 — ENGINE (invisible to agent, 0 tokens)
|
+-- engine/
|   +-- (CRM integration, email API, SQLite pipeline DB, lead scoring model)
|      Pluggable: SQLite FTS5, sqlite-vec, Qdrant, Ollama, OpenAI, Neo4j
|
|  PROJECT LAYER — What agents BUILD
|
+-- output/
|   +-- proposals/
|   +-- analyses/
|   +-- reports/
|   +-- sequences/
|
+-- data/
|   +-- leads.csv
|   +-- pipeline.json
|   +-- call-notes/
|
+-- .canopy/                  Runtime state (gitignored)
    +-- tasks/
    +-- sessions/
    +-- observations/

Manifest Types

TEAM.md — Defines an org subtree. Teams group agents, own a shared budget slice, and declare their coordination protocol.

PROJECT.md — Defines planned work with milestones, budget allocation, and resource assignments. Carries explicit evidence gates.

TASK.md — Portable, reusable task definition. Assigned to agents, tracked through the task hierarchy.

---

Agent Library

330+ pre-built agents across 19 categories:

Category	Examples
Engineering	backend, frontend, devops, security, performance, database
Sales	director, prospector, closer, researcher, copywriter
Marketing	strategist, content writer, SEO, growth, analyst
Operations	project manager, coordinator, HR, finance
Research	analyst, scientist, intelligence, competitive
Design	UI/UX, brand, product
Legal	contract review, compliance, IP
Finance	CFO, controller, FP&A
Customer Success	CSM, support, onboarding
Product	PM, roadmap, discovery
Executive	CEO, CTO, CPO, CMO
Infrastructure	SRE, platform, cloud
AI/ML	data scientist, model trainer, ML engineer

Browse the library in the Command Center or drop any agent file into your agents/ folder.

---

Adapters

Canopy dispatches work to any connected runtime. Eleven adapters — five fully functional, six in beta:

Adapter	Status	Install
OSA	Functional	curl -fsSL https://raw.githubusercontent.com/Miosa-osa/OSA/main/install.sh | bash
Claude Code	Functional	npm install -g @anthropic-ai/claude-code
Codex	Functional	npm install -g @openai/codex
Bash / HTTP	Functional	Built-in
Cursor	Beta	cursor.sh
Gemini	Beta	ai.google.dev
OpenClaw	Beta	npm install -g openclaw
Aider	Beta	pip install aider-chat
JidoClaw	Beta	curl -fsSL https://raw.githubusercontent.com/robertohluna/jido_claw/main/install.sh | bash
Windsurf	Beta	codeium.com/windsurf

The Command Center auto-detects installed adapters and provides one-click setup wizards. Provider credentials are stored in the OS keychain via Tauri's secure store.

All adapters implement the Canopy.Adapter behaviour: execute/2, stream/2, health/1, capabilities/0.

---

Pre-Built Workspaces

Workspace	Description
sales-engine	B2B pipeline: prospecting, qualification, demos, close
dev-shop	Software agency: planning, coding, review, deployment
content-factory	Content production: strategy, writing, editing, publishing
cognitive-os	Personal second brain: capture, process, connect, retrieve
custom	Blank slate with full scaffolding

---

Backend API

Scope

Metric	Count
Controllers	54
Schemas	56
Migrations	67
Routes	~151
Adapters	11

Key Subsystems

Module	Purpose
Canopy.Heartbeat	9-step agent execution cycle with Quantum scheduling
Canopy.BudgetEnforcer	ETS atomic counters, 5-level cascade, hard stop enforcement
Canopy.Governance.Gate	Plug-based approval enforcement on spawn/delete/budget/strategy
Canopy.Governance.Executor	Replays approved actions (spawn, delete, budget override)
Canopy.Dispatch.Router	Content-based adapter routing with label + regex matching
Canopy.Dispatch.Delegation	Subtask creation with adapter-aware agent selection
Canopy.Sessions.Compactor	Session summarization, handoff generation, context injection
Canopy.Sessions.Chain	Linked session chains with cumulative token tracking
Canopy.Workflows.Engine	DAG workflow execution with topological sort and retry
Canopy.Workflows.Scheduler	Cron-based workflow triggering
Canopy.Notifications.Dispatcher	Multi-channel notification creation and broadcasting
Canopy.EventBus	Phoenix PubSub topic management for real-time updates
Canopy.IssueDispatcher	Task assignment with priority queue and team routing

---

Development

Prerequisites

• Elixir 1.15+
• Node.js 20+
• PostgreSQL 15+
• Rust (for Tauri)

Make Targets

make setup       # Install all dependencies and create the database
make dev         # Start backend + frontend in development mode
make backend     # Start Phoenix backend only (:9089)
make desktop     # Start SvelteKit + Tauri desktop app (:5200)
make test        # Run full test suite
make lint        # Run Elixir + TypeScript linters
make format      # Auto-format all code
make build       # Production build
make release     # Build and package the Tauri desktop app
make db.reset    # Drop, create, migrate, and seed the database
make db.migrate  # Run pending migrations

Environment

The backend reads from .env in the project root. Required variables:

DATABASE_URL=postgres://localhost/canopy_dev
SECRET_KEY_BASE=...         # mix phx.gen.secret
GUARDIAN_SECRET_KEY=...     # mix guardian.gen.secret

Optional variables for adapter credentials live in .env.local and are never committed.

Ports

Service	Port
Phoenix backend	:9089
SvelteKit desktop	:5200
OSA integration	:8089

Running Tests

mix test                     # Backend tests
cd desktop && npm run test   # Frontend tests
make test                    # Both

---

Theoretical Foundation

Canopy implements the Optimal System architecture from Signal Theory: The Architecture of Optimal Intent Encoding (MIOSA Research, 2026). The protocol's directory structure, agent format, progressive disclosure, and governance model directly implement the paper's 7-layer system:

1. Network — company.yaml and reportsTo define who connects to whom
2. Signal — S=(M,G,T,F,W) encodes intent across 5 dimensions
3. Composition — Agent body sections and skill steps define micro-structure
4. Interface — Progressive disclosure (L0/L1/L2) surfaces the right context
5. Data — Markdown files are the storage substrate for organizational intent
6. Feedback — Heartbeat cycles and quality gates close every loop
7. Governance — SYSTEM.md encodes Beer's Viable System Model recursively

Every design decision traces to one of four governing principles: Shannon (channel capacity), Ashby (requisite variety), Beer (viable structure), Wiener (feedback closure).

---

Ecosystem

Canopy (protocol)   ->  Any agent reads it. Free. MIT license.
Command Center      ->  Native desktop app. Free. Open source.
MIOSA (platform)    ->  Managed VMs, marketplace, enterprise. Paid.

Canopy is the open-source foundation. MIOSA provides managed infrastructure, a marketplace for buying and selling agent workspaces, and enterprise governance tools built on top of the same protocol.

---

Repository

https://github.com/Miosa-osa/canopy

Architecture reference docs live in architecture/:

• architecture/heartbeat.md — 9-step heartbeat protocol
• architecture/adapters.md — runtime adapter interface
• architecture/budgets.md — budget enforcement model
• architecture/governance.md — approval gate system
• architecture/tasks.md — task coordination protocol
• architecture/sessions.md — session persistence and compaction
• architecture/dispatch.md — dynamic adapter routing
• architecture/workflows.md — DAG workflow engine
• architecture/hierarchy.md — 5-layer organizational structure
• architecture/processing-pipeline.md — 6R knowledge pipeline

---

Contributing

1. Fork the repo and create a branch from main
2. Run make setup && make test to verify your environment
3. Make changes with tests
4. Submit a pull request with a clear description of what changed and why

Code style is enforced by make lint and make format. PRs that don't pass CI will not be merged.

---

License

MIT — see LICENSE.