Canopy

Infrastructure for agent-native applications, with pluggable runtimes.

Canopy is a framework for building multi-user AI agent products where .md files define the agent’s behavior, memory, and capabilities. Each user gets an isolated Workspace — a directory that an agent runtime runs against. Canopy infra provisions Workspaces from templates, handles triggers, spawns runtime instances, and routes output. The runtime is pluggable — Claude Code is the default, but any coding agent (Aider, Open Interpreter, or a custom binary) can be configured via CANOPY_RUNTIME.

These docs are an implementation spec: copy this folder into your project, point Claude at it, and it can build the entire Canopy platform for your agent.

---

Quick Start

# 1. Install
pip install canopy-cli

# 2. Create a workspace from the Codebase Navigator example
canopy create myteam myuser
# → provisions workspaces/myteam_myuser/ from examples/codebase-navigator/

# 3. Connect and start a session
canopy connect myteam_myuser
# → opens an interactive agent session in that workspace

# 4. Or run a one-shot prompt
canopy run myteam_myuser -p "Explain the top-level architecture of this project"

---

How It Works

1. Developer authors a template (CLAUDE.md, skills, agents, tool configs, settings.json)
2. Canopy infra provisions a Workspace directory for each user from the template
3. Trigger arrives (chat message, scheduled task, webhook)
4. Canopy infra spawns the agent runtime against the Workspace directory → captures stdout

That’s it. No custom runtime code, no prompt assembly, no tool dispatch logic. The agent runtime handles context loading, skills, sub-agents, MCP tools, memory, and sandboxing natively. When using Claude Code (the default), this means CLAUDE.md loading, slash commands, agents, and auto-memory — all built in.

---

Install

Requires Python 3.12+ and uv.

Run without installing (recommended for development):

uv run --directory canopy/cli canopy --help

Install as editable package:

uv pip install -e canopy/cli
canopy --help

Full reference: cli/README.md

---

CLI

Global: --env-file PATH. Auto-loads canopy/.env if present. Env var: CANOPY_WORKSPACE_BASE_PATH (default: /tmp/canopy/workspaces). All name arguments support fuzzy (substring) matching.

See cli/README.md for full details.

---

What is this?

Canopy is infrastructure for building multi-user AI agent products. Think of it like Docker for agents:

---

Core Concepts

---

Quickstart

To adopt Canopy in your project, answer five questions:

1. What does your agent do?

Example: “Personal executive assistant that manages Slack, Calendar, and Email” Example: “SRE agent that queries logs, metrics, and traces from an observability platform”

2. What tools does it have?

List the external APIs and actions the agent can perform (these become MCP servers). Example: messaging_read, messaging_send_draft, calendar_read, calendar_create, monitoring_query_logs

3. What’s per-user vs global?

What data is the same for all users (template) vs unique per user (preferences, memory)? Example: Agent personality = global. User’s communication style = learned per user.

4. What’s your existing stack?

What auth, database, and frontend do you already have? Example: “Clerk auth, PostgreSQL, Next.js frontend, OAuth tokens for Slack and Google”

5. Where should the Workspace layer plug in?

Is this replacing your entire agent system, or enhancing an existing one? Example: “Replace — our current OpenAI Agents SDK setup is being retired” Example: “Enhance — add per-org learned context to our existing multi-agent system”

With these answers, Claude can read this framework and build the Canopy layer for your specific product.

---

Example Templates

Three ready-to-use templates in examples/, each showcasing a different Canopy capability:

Use one as-is or as a starting point for your own template:

canopy create myteam myuser --template codebase-navigator
canopy create myteam myuser --template release-pilot
canopy create myteam myuser --template daily-standup

---

Framework Documentation

Reference Templates

These files show the expected structure and conventions for each file type. Claude uses them as reference when generating your template folder.

---

Philosophy

1. Documents are the database. The agent’s personality, memory, skills, and knowledge are .md files. No ORM. No migrations. The LLM reads and writes them natively.

2. Skills are functions. A skill is a prompt template with a trigger, steps, and output format. Creating a new capability means writing a .md file, not writing code.

3. The LLM is the CPU. The runtime reads documents, reasons, calls MCP tools, writes memory. It provides the intelligence. Canopy provides the infrastructure.

4. Code is only for I/O. Auth, credentials, webhooks, process management, output routing — these need code. Everything else — personality, behavior, memory, skills — is documents.

5. Don’t build what the runtime gives you. Context loading, skills, sub-agents, MCP tools, memory, hooks, sandboxing — leverage what’s native. Claude Code provides all of these out of the box; other runtimes may provide a subset.

---

Status

Canopy is in active development. The CLI (cli/) is functional — create, inspect, connect, run, and delete workspaces. The runtime is configurable via CANOPY_RUNTIME (default: claude-code; supports any binary via custom). The framework specification docs define the full architecture. 90+ tests with CI via GitHub Actions.

---

Contributing

Canopy is in its early stages. Contributions welcome:

• Architecture feedback — open an issue with suggestions for the pattern
• Worked examples — submit a PR adding your product type to the Adoption Guide
• MCP server examples — reference MCP server implementations for common integrations
• Bug reports — found an inconsistency or gap in the docs? Let us know

---

License

Apache 2.0