██████   ██████   ████████    ██████  ████████  █████ ████
 ███░░███ ░░░░░███ ░░███░░███  ███░░███░░███░░███░░███ ░███ 
░███ ░░░   ███████  ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ 
░███  ███ ███░░███  ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ 
░░██████ ░░████████ ████ █████░░██████  ░███████  ░░███████ 
 ░░░░░░   ░░░░░░░░ ░░░░ ░░░░░  ░░░░░░   ░███░░░    ░░░░░███ 
                                        ░███       ███ ░███ 
                                        █████     ░░██████  
                                       ░░░░░       ░░░░░░   

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, loop 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

Platform	Binary	Ships as
claude	claude	terminal (Claude Code)
codex	codex	terminal (Codex CLI)
gemini	gemini	terminal (Gemini CLI)
copilot	copilot	terminal (GitHub Copilot CLI)
qwen	qwen	terminal (Qwen Code)
mistral	vibe	terminal (Mistral's Vibe CLI)
opencode	opencode	terminal (OpenCode)
kiro	kiro-cli	terminal (Kiro)
kilo	kilo	terminal (Kilo Code)
cline	cline	editor (Cline, VS Code)
continue	cn	editor (Continue, VS Code/JetBrains)
blackbox	blackbox	terminal (Blackbox AI CLI)
mimocode	mimo	terminal (Mimo Code)
cursor	agent	editor (Cursor)
antigravity	agy	editor (Antigravity)
qoder	qoder	editor (Qoder)

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 is meant to detect nothing, say so, list every platform it supports, and finish with zero platforms configured so you can install one and re-run. In practice it doesn't reach that message: the registry fetch (src/setup_module/registry_fetch.rs, try_fetch_v6 / try_fetch_v5 / try_fetch_local) filters the platform list down to already-installed binaries before returning it, and bails out if that filtered list is empty — discarding the full list that the "no platforms detected" branch (src/setup_module/wizard.rs:50-61) needs. Verified by running canopy setup with no supported binary on PATH: the real registry path fails with Error: Registry returned HTTP 404 Not Found (it falls through to a dead legacy endpoint), and canopy setup --local-registry <dir> fails with Error: Local registry not found or invalid at: <dir>. Either way, setup exits instead of guiding you — this is a bug in canopy setup, tracked separately, not fixed here.

---

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, loops, the RAG pipeline, all 83 MCP tools, and the complete CLI reference.

---

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, loops, and projects are stored in an embedded SQLite database with WAL mode and automatic schema migration.
• 🔄 Auto-Update — Checks GitHub releases daily for new stable versions, downloads the platform-specific binary (linux-musl, macos-darwin; x86_64/aarch64), and atomically replaces the running executable.
• 🔔 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 loop_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), section picker, and @-mention agent references.
• 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, relates_to, independent) 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).

🔀 Loop DAG Engine

• Ordered Specs — Loops contain sequenced Specs, each with Nodes connected by Edges with routing conditions (pass/fail/always).
• Standalone Spec Backlog — Specs exist independently from loops; 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 loop drains one by one. Append and reorder while a loop is running via queue_create, queue_add_spec, queue_list, queue_remove_spec, queue_reorder.
• 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 — loop_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. loop_update_ensemble edits the shared prompt, member list, and quorum/exit config as one unit. See docs/loops.md.
• Node Blueprints — Reusable {name, kind, config} templates referenced by name in loop_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. loop_schedule_autorun resumes failed/completed loops at a future time. Archive and restore loops without losing history. Export and import loop designs as shareable JSON documents. Copy nodes and ensembles within or across loops. View node run history for failure diagnosis.
• on_completed Hook — Post-completion agent execution (e.g. documentation maintenance) that fires once per completion.
• Template Variables — Loop prompts support {{loop_name}}, {{workdir}}, {{spec_id}}, {{spec_name}}, {{spec_content}}, {{node_id}}, {{previous_feedback}}, and {{spec_start_head}} (git HEAD at spec start, for check nodes).
• 24 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) or remote APIs (OpenAI, Gemini).
• 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 Loop 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 loops, backlog specs, and loop history, filterable by project workdir.
• Loop 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 with auto-noise for idle state visualization.
• Whimsg — Animated kaomoji status messages with typing effects.
• Gamification — 28 achievement-style missions across 6 categories (Environment, Intelligence, Projects, Loop, Seeds, SysInfo) tracked automatically during normal TUI operation.

🔧 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.
• 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 loop lifecycle (started, spec completed, finished with outcome, blocker, hook failure).

---

MCP Tools (83)

Category	Tools
Agent Management (14)	agent_add, agent_watch, agent_list, agent_remove, agent_enable, agent_disable, agent_schedule_enable, agent_run, agent_status, agent_models, agent_logs, agent_update, agent_report, agent_probe
Multi-Agent Sync (4)	sync_declare_intent, sync_report_status, sync_broadcast, sync_get_context
Intelligence V2 (8)	intelligence_get_context, intelligence_upsert, intelligence_search, intelligence_graph_walk, intelligence_list_projects, intelligence_link_projects, intelligence_delete_node, intelligence_delete_relation
Seed Identity (5)	get_identity, evolve_identity, create_seed, list_seeds, remove_seed
Loop Engine (32)	loop_create, loop_update, loop_add_spec, loop_update_spec, loop_add_node, loop_update_node, loop_add_edge, loop_update_edge, loop_delete_edge, loop_delete_node, loop_add_ensemble, loop_update_ensemble, loop_get, loop_list, loop_run, loop_reset, loop_schedule_autorun, loop_pause, loop_continue, loop_complete_node, loop_report_blocker, loop_export, loop_import, loop_archive, loop_restore, loop_node_runs_list, loop_node_run_get, loop_copy_node, loop_copy_ensemble, loop_audit_node_configs, loop_schedule_continue, loop_preflight
Spec Backlog (5)	spec_create, spec_list, spec_update, spec_delete, spec_set_status
Spec Queues (5)	queue_create, queue_add_spec, queue_list, queue_remove_spec, queue_reorder
Node Blueprints (3)	blueprint_list, blueprint_create, blueprint_delete
Project (3)	project_search, project_update, project_remap
RAG (1)	rag_search
Protocol (1)	get_tools

---

Architecture Overview

• Daemon — Owns the MCP server (Streamable HTTP on port 7755 + stdio), scheduler, watcher engine, and database. Exposes all 83 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.
• Loop 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, loops, 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, loops, projects, seeds, groups, state)
• domain/ — Core models: Agent, Trigger, WatchEvent, Project, SeedIdentity, Loop, LoopSpec, Queue, LoopNodeBlueprint, 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
• loop_engine/ — DAG loop execution engine

---

Data Storage

Data	Location	Format
Structured data	~/.canopy/background_agents.db	SQLite (WAL mode)
Vector embeddings	~/.canopy/rag/vectors.lancedb	LanceDB
Seed identities	~/.canopy/seeds/<id>/identity.toml	TOML
Terminal history	~/.canopy/terminals/<name>/history.toml	TOML
Configuration	~/.canopy/config.toml	TOML
Agent logs	~/.canopy/logs/<id>.log	Text (5 MB rotation)
Daemon log	~/.canopy/daemon.log	Text
RAG indexed files	~/.canopy/rag/	Markdown, PDF

---

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 daemon auto-updates to stable releases every 24 hours.

---

Tech Stack

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

---

License

MIT — see LICENSE for details.

---

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