AI代理编排服务

harness-canopy is a modern, self-contained MCP (Model Context Protocol) server and TUI for orchestrating AI agent sessions, background tasks, and file event triggers. Designed for reliability, modularity, and performance — it enables advanced scheduling, persistent knowledge graphs, multi-agent coordination, graph automation, and interactive terminal management with zero runtime dependencies.

Demo

Requirements

canopy orchestrates AI agent tools — it doesn't ship one. Before installing, you need at least one supported platform installed and authenticated on this machine. "Installed" is not enough: the most common first failure is a platform that's present but not logged in, and canopy has no way to tell you apart from "canopy is broken."

canopy calls each supported AI tool a platform. Most ship as a standalone terminal command (claude, codex, gemini, ...); a few — Cursor, Antigravity, Qoder — ship as a code editor with one built in. canopy drives either kind the same way, through the CLI binary each one exposes, so editors show up in the same list as terminal tools.

Supported platforms

This list is drawn from the live platform registry (index.toml); canopy setup re-fetches it, so newly added platforms show up there before they show up here.

Check that a platform is usable

canopy doctor

Its "Harnesses" line confirms each configured platform's binary is present and executable on PATH — it does not check that you're logged in. There's no single command across all 16 platforms for that; check the platform's own way, e.g. claude auth status or codex login status. Most tools will otherwise tell you the moment you actually run them for real.

If no platform is installed

canopy setup detects nothing, lists every supported platform with its CLI binary name, and exits cleanly without writing any configuration. Install one of the listed binaries, make sure it's on your PATH, then re-run canopy setup.

Installation

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/UniverLab/harness-canopy/main/scripts/install.sh | sh

Or via cargo: cargo install harness-canopy (the binary is canopy). See docs/installation.md for all methods and first-time setup.

Documentation

Full documentation lives in docs/: installation, quick start, the TUI, agents and seed identities, intelligence & sync, graphs, the RAG pipeline, all MCP tools, and the complete CLI reference.

Contributing

docs/ is published at univerlab.org/canopy/docs and holds user documentation only; design records are kept outside the repository.

Features

🎯 Core Platform

• 🚀 High-Performance Scheduler — Event-driven cron scheduler using Tokio with zero polling overhead. Computes precise wake-up times and sleeps until needed; CPU usage drops to near-zero when idle.
• 📊 Real-time File Watcher — Instantly reacts to file system events (create, modify, delete, move) using the notify crate with configurable debouncing, recursive directory monitoring, and macOS FSEvents compatibility.
• 💾 Persistent State — All tasks, watchers, execution logs, agent state, sync messages, intelligence nodes, graphs, and projects are stored in an embedded SQLite database with WAL mode and automatic schema migration.
• 🔄 Auto-Update — canopy update checks GitHub releases for a newer stable version, asks first (default no), refuses cargo installs, and restarts the daemon. canopy update --check exits 0 (up to date), 1 (update available), or 2 (check failed).
• 🔔 Cross-Platform Notifications — Native desktop notifications for task completions, failures, and watcher triggers. Auto-detects platform: WSL (PowerShell toasts with AUMID), macOS (osascript), Linux (notify-send).

🤖 Agent Management

• Interactive PTY Agents — Each agent runs in a dedicated pseudo-terminal with full vt100 emulation, 24-bit color support, cursor positioning, and interactive applications.
• Terminal Sessions — Raw shell sessions with per-session command history (TOML-backed), cross-session autocomplete search, and Warp-like input mode for efficient command entry.
• Background Agents — Cron-scheduled and file-watcher-triggered agents with configurable timeouts, automatic retries, execution logging (5 MB rotation), and per-run status tracking.
• Platform Liveness Probe — agent_probe tests whether a platform+model pair can actually respond before graph_run spends real quota on it. Probes the exact pair a node would use, not just the platform default.
• Seed Identity System — Persistent, evolvable agent identities stored as structured TOML at ~/.canopy/seeds/<id>/identity.toml. Each seed has a unique name, family, behavioral directives, and personality traits. Binded sessions receive the seed's prompt injection automatically. The evolve_identity MCP tool lets agents refine themselves over time. 4 KB size cap, case-insensitive name uniqueness, and mandatory field validation.
• Seed Nursery — Collaborative workspace for creating new seed identities. Creates a temporary directory with a draft identity.toml and CLI-specific instruction files (e.g. CLAUDE.md, AGENTS.md) that guide the agent to interview the user and define the seed's personality. Validates and registers the seed on completion.
• Context Transfer — Seamlessly transfer conversation context, prompts, and output between agents while preserving session state and scrollback history.
• Prompt Builder — Structured prompt templates with configurable sections (instruction, context, resources, examples, Canopy protocol), section picker, and @-mention agent references. The session-start Canopy protocol rides on the first prompt of an interactive session only — persisted per session across restarts and resumes — and the locked Canopy protocol section (Ctrl+A) resends it on purpose.
• Launchpad — Start new interactive sessions with previous mission recovery, mission input, and auto-injected context.

🧠 Intelligence V2 — Knowledge Graph

• Project-Scoped Knowledge — Store facts, patterns, and session summaries scoped to individual projects via project_hash (SHA-256 of canonical workdir path, truncated to 8 hex). Auto-detected from the session workdir — agents never need to set it manually.
• Full-Text Search — Search intelligence nodes by query and optional kind filter across all projects.
• Graph Walk — Traverse the knowledge graph from any node up to a configurable depth, returning connected facts, patterns, and cross-references.
• Project Relationships — Link projects with typed relations (depends_on, complements, extends, publishes; relates_to accepted as legacy, contains derived) and query related projects for context enrichment.
• Context Retrieval — intelligence_get_context auto-detects the project, returns a curated mix of session knowledge, project facts, and related-project summaries.

🔄 Multi-Agent Sync

• Mission Declaration — Agents declare high-level missions with impact levels (low/high/breaking) so peers can see what's happening.
• Workspace Status — Report workspace stability (stable/unstable/testing) to coordinate safe concurrent work.
• Broadcast Messaging — Info, query, and answer messages between agents in the same workdir.
• Active Context — sync_get_context returns active missions, recent chatter, and a computed workspace "vibe" (worst status among active intents).

🔀 Graph DAG Engine

• Ordered Specs — Graphs contain sequenced Specs, each with Nodes connected by Edges with routing conditions (pass/fail/always).
• Standalone Spec Backlog — Specs exist independently from graphs; tag them to a workdir for filtering. Managed via spec_create, spec_list, spec_update, spec_delete.
• Spec Queues — Ordered queues of existing specs that a graph drains one by one. Append and reorder while a graph is running via queue_create, queue_add_spec, queue_list, queue_remove_spec, queue_reorder, queue_set_group.
• Node Kinds — agent nodes invoke CLI tools with prompt templates; check nodes execute shell commands; gate nodes validate previous output (e.g., output_contains); router nodes classify and route by token matching with fallback; quorum is the engine-managed node that closes an ensemble.
• Ensembles — graph_add_ensemble creates a parallel group of 2-8 agent-node members sharing one prompt (or per-member prompt overrides for specialist panels), plus a wait-all quorum that consolidates their outputs and routes onward, in a single MCP call. graph_update_ensemble edits the shared prompt, member list, quorum/exit config, and entry wiring (including multi-source entry and chaining a quorum into another ensemble) as one unit; graph_delete_ensemble removes the whole unit. See docs/graphs.md.
• Node Blueprints — Reusable {name, kind, config} templates referenced by name in graph_add_node. Five builtins seeded at startup; custom blueprints via blueprint_create/blueprint_delete/blueprint_list.
• Full Lifecycle — Create, update, run, pause, continue (retry or skip), reset, complete nodes, and report blockers for human intervention. graph_schedule_autorun resumes failed/completed graphs at a future time. Archive and restore graphs without losing history. Export and import graph designs as shareable JSON documents. Copy nodes and ensembles within or across graphs. View node run history for failure diagnosis.
• Event-keyed Hooks — Agent execution, direct shell commands, or interactive messages into a live session on on_completed, on_failed, on_blocked, and on_spec_completed (e.g. documentation maintenance fires once per completion; a failing graph at midnight puts a message in the operator's session, delivered when they next open the TUI). Several hooks can serve one event in order; hooks are not retroactive and never change the graph's status.
• Template Variables — Graph prompts support {{graph_name}}, {{workdir}}, {{spec_id}}, {{spec_name}}, {{spec_content}}, {{spec_code}}, {{spec_type}}, {{spec_scope}}, {{spec_commit_message}}, {{node_id}}, {{previous_feedback}}, and {{spec_start_head}} (git HEAD at spec start, for check nodes).
• MCP Tools — Complete authoring, inspection, runtime, spec, queue, and blueprint management.

📚 Personal RAG Pipeline

• Semantic Search — Embed and query personal documents (Markdown, MDX, PDF) with local ONNX models (fastembed/BGE, multilingual-e5). No cloud provider, no API key.
• Language-Aware Chunking — Markdown split by headings with paragraph fallback, similarity-aware merging, and overlap for context preservation.
• PDF Extraction — Isolated subprocess prevents parser crashes from taking down the daemon, with HTML detection and raw-text salvage fallback.
• Auto-Ingestion — Background watcher monitors configured RAG roots with 3-second debounce, enqueues changes, and reconciles orphan chunks on startup.
• Per-Agent Rate Limiting — 10 calls/minute sliding window per agent.
• .canopy/ragignore — Regex-based exclusion patterns for files and directories.

🖥️ Interactive TUI (Canopy Hub)

• NewAgentDialog — Three modes (Interactive, Background Cron/Watch, Terminal) with CLI picker, model picker, seed identity selector (◀ None / SeedName ▶), directory browser, and yolo mode toggle.
• Scheduled Delivery — Shift+Enter (Kitty keyboard protocol) sends prompts at a chosen time instead of immediately.
• Split Groups — Side-by-side horizontal/vertical views for monitoring multiple agents simultaneously.
• System Dashboard — CPU, memory, disk, GPU (NVIDIA/Linux/macOS), temperatures with amber/red alert thresholds. WSL queries Windows host metrics via PowerShell.
• Live Graph View — Real-time graph rendering with auto-follow on the running node, manual node inspection, and per-node run info (status, elapsed, output tail).
• Agent Status Colors — Green for working (recent output), blue for idle, red for failed, gray for exited.
• Projects Sidebar — Sections for active graphs, backlog specs, and graph history, filterable by project workdir.
• Graph Editor — Inline node config JSON editing with validation.
• RAG Transfer Modal — Send semantic search results to other agents as injected context.
• Context Transfer — Two-step modal (preview → agent picker) to inject conversation context between sessions.
• Brian's Brain — 3-state cellular automaton drawn as Braille glyphs; the cursor seeds clusters along its path at a fixed step rate.
• Whimsg — Animated kaomoji status messages with typing effects: curated forest-voice phrases and deliberate jokes, or a real-event message naming the agent, graph, or spec that just happened.
• Gamification — 28 achievement-style missions across 6 categories (Environment, Intelligence, Projects, Graph, Seeds, SysInfo) tracked automatically during normal TUI operation; list them read-only with canopy missions [--json].

🔧 Additional Features

• Prompt Template Engine — Background agent prompts support {{TIMESTAMP}}, {{TASK_ID}}, {{LOG_PATH}}, {{FILE_PATH}}, {{EVENT_TYPE}} placeholders.
• Project Registry — Automatic project index keyed by workdir hash. README descriptions extracted from project roots (min 20 words, before first ## heading). Search and update via project_search and project_update MCP tools.
• Action Protocol Advisor — get_tools MCP tool returns scope-sensitive action protocols (session_start, file_write, test_run, close_session, multi_agent) with risk levels and recommended tool sets.
• Setup Wizard — Interactive canopy setup detects installed AI CLIs from a GitHub-hosted registry, configures binary paths, model flags, headless modes, environment variables, and temperature units. Generates ~/.canopy/config.toml.
• On-Demand Registry Refresh — canopy registry refresh applies the platform registry to config.toml now, ignoring the 24-hour window the TUI's background refresh uses at startup. Reports the CLI fields it changed, the local overrides it kept, and the platforms added, updated or removed. The registry_refresh MCP tool does the same from an agent session.
• MCP Wizard — canopy mcp subcommand for syncing, adding, and removing MCP server entries across all detected platforms with automatic format conversion (JSON ↔ TOML).
• Skills Manager — Global skill directory at ~/.agents/skills/ with cross-platform symlinks. List, validate symlink integrity, and remove installed skills across platforms.
• Doctor Diagnostics — canopy doctor checks data directory, database, config, harnesses, RAG status, file watchers, daemon process, registry connectivity, and auto-update health.
• Desktop Notifications — Cross-platform alerts for task completions, failures, watcher triggers, RAG indexing events, and graph lifecycle (started, spec completed, finished with outcome, blocker, hook failure).

MCP Tools (116)

Graph-node sessions (agent and ensemble nodes launched by the graph engine) receive a fixed node profile of 18 tools via CANOPY_MCP_PROFILE=node, so every node stays well under the 128-tool cap of OpenAI-compatible providers. All other sessions — the orchestrator, check nodes, hooks, TUI, subagents, and background agents — keep the full tool list.

Architecture Overview

• Daemon — Owns the MCP server (Streamable HTTP on port 7755 + stdio), scheduler, watcher engine, and database. Exposes all MCP tools.
• Scheduler — Computes next fire times for all active tasks, sleeping until needed. Wakes instantly on changes.
• Watcher Engine — Reacts to file system events, triggering tasks as defined.
• Executor — Runs tasks and agents, manages locking, logs, and status.
• Intelligence V2 — Project-scoped knowledge graph with node/edge CRUD, deletion tools, graph walk, project relationships.
• Sync Manager — Per-workdir in-memory broadcast channels (64 capacity), DB persistence, and intelligence node auto-upsert.
• Graph Engine — DAG execution engine: agent/check/gate/router node runners, iteration limits, pause/continue, blocker reporting, spec queues, node blueprints, scheduled autorun, archive/restore, export/import, node run history, and copy tools.
• RAG Pipeline — Background ingestion, language-aware chunking, embedding client, vector store, and rate-limited search.
• TUI — Full-screen ratatui terminal UI for managing agents, viewing output, graphs, and system metrics in real time.
• Gamification — Mission tracker with 28 achievements across 6 categories, persisted in the database.
• Skills Manager — Global skills directory with cross-platform symlinks and integrity validation.

Main Modules

• application/ — Application ports and abstractions
• autoupdate/ — Self-update system (GitHub releases)
• daemon/ — MCP server, handler, params, RAG CLI, doctor
• db/ — SQLite persistence and migrations (agents, runs, sessions, sync, intelligence, graphs, projects, seeds, groups, state)
• domain/ — Core models: Agent, Trigger, WatchEvent, Project, SeedIdentity, Graph, GraphSpec, Queue, GraphNodeBlueprint, SyncMessage, IntelligenceNode
• executor/ — Task and agent execution logic
• rag/ — RAG pipeline (ingestion, chunking, embedding, vector store, rate limiting)
• scheduler/ — Internal cron scheduler with template variables
• sync_manager/ — Multi-agent coordination broadcast
• tui/ — Terminal UI: agent management, dialogs, sidebar, system dashboard, context transfer
• watchers/ — File system watcher engine
• graph_engine/ — DAG graph execution engine

Data Storage

Usage

1. Start the daemon:

   复制

   canopy daemon start
   

2. Configure (first time):

   复制

   canopy setup
   

   Choose AI CLI platforms, model flags, temperature units, and RAG settings. Generates ~/.canopy/config.toml.

3. Launch the TUI:

   复制

   canopy
   

   Opens the full-screen Canopy Hub. Press Ctrl+N or n to create a new agent (Interactive, Background, or Terminal). Select a seed identity to give the agent a persistent personality.

4. Check health:

   复制

   canopy doctor
   

5. Manage MCP servers across platforms:

   复制

   canopy mcp
   

6. RAG indexing:

   复制

   canopy rag auto-index start   # Start background watcher
   canopy rag auto-index stop    # Stop
   canopy rag report             # Per-file indexing report
   

All state persists in ~/.canopy/. The TUI shows an update notice at most every 24 hours — canopy update installs it.

Tech Stack

|Rust 2021| Tokio | Axum | rusqlite | LanceDB | notify | vt100 | ratatui | clap | serde | tracing | fastembed |

License

Licensed under either of MIT or Apache-2.0, at your option. Releases up to 3.0.1 were published under MIT only.

An experiment of UniverLab — an open computational laboratory. Made with ❤️ by JheisonMB