Skip to content
Canopy is in pre-release. These docs describe the product at its public launch — commands, tool names, and integration examples reflect what you'll see once binaries ship. Join the waitlist →

v2.0.0 — One routed tool, setup-first onboarding, honest answers

Versions: 2.0.0-alpha series (current)

Canopy 2 is the single-tool redesign. Everything the v1.x series built — the AST index, the dependency graph, full-text + semantic search, health checks — is still the engine. What changed is the surface: instead of exposing a 31-tool catalog for the agent to orchestrate, Canopy exposes one tool, canopy_answer, and routes each question to the right recipe internally.

This is a breaking major, and it’s the one the benchmarks demanded: a control arm that handed the agent the full v1 tool catalog spent 2.3×–5.8× more tokens than shell, while the single routed call beats shell on both correctness (+76%) and cost (−69% tokens) on the 270-question library suite. The tool catalog wasn’t the product — the answer is.

The single tool

Section titled “The single tool”
  • The MCP surface is canopy_answer — one call, natural-language question in, cited answer out. The CLI twin is canopy answer "<question>".
  • Routing is a deterministic, corpus-validated classifier — 360/360 on its labelled regression corpus. No LLM call, no network, no latency tax.
  • Phrasing picks the recipe: name the entity type and backtick paths and symbols. Fourteen question shapes cover locate, extract, file comprehension, public surface, dependents/blast-radius, imports, ownership, test coverage, dead-code wiring, import cycles, pre-edit dossier, filtered symbol listings, architecture overview, and a semantic concept fallback.
  • The question shapes are frontloaded into the tool description, the server instructions, and canopy answer --help, so agents and humans learn the phrasing without leaving the session.
  • All 31 v1 tools are removed. The v1.0.0 MCP freeze ended with this major.

Honest answers

Section titled “Honest answers”
  • Relevance floor: every semantic answer is scored by a cross-encoder; when nothing clears the calibrated floor, Canopy declines with “No strong match in this repository” instead of relaying tangential files with false confidence. A nonsense question, an out-of-domain question, and a question about code that doesn’t exist all get the same honest empty — with phrasing suggestions.
  • Empty Tier-A results now name their cause (no summary index / stale index / healthy-but-no-match) instead of an indistinguishable “0 hits”.

Setup-first onboarding

Section titled “Setup-first onboarding”
  • Three commands end to end: install → canopy setup → canopy answer.
  • canopy setup runs the whole onboarding — license, embedding runtime (Ollama + nomic-embed-text), summary backend, CI cache, automatic editor wiring for every detected MCP client, and the first index. Each step has a one-Enter default; --yes runs unattended; --only/--skip scope steps; --bundle-path installs the embedding runtime offline from a tarball or directory.
  • canopy doctor is the one-stop readiness view: install info, license tier, index status, would-activate summary backend, the data-flow line, and cloud-credential presence.
  • canopy index builds everything by default (AST + full-text + embeddings, git auto-ingested when .git/ is present). .canopyignore joins .gitignore and the bundled defaults for repo-specific exclusions; --list-ignored audits the exclusion set.

Licensing and seats, end to end

Section titled “Licensing and seats, end to end”
  • canopy deactivate releases this machine’s seat server-side and drops the local install to Community — fail-closed when offline, so a failed release never strands a seat.
  • Seat transfer (evicting a stale machine at activation time) now updates the server’s seat ledger only. The license key and its hash never change — no other machine on the license is ever disturbed by a transfer.
  • The licensing API moved to its production domain, heartbeat.canopy.gulfshieldtech.com.
  • Self-update (canopy update) is fail-closed behind an Ed25519 manifest signature plus SHA-256 verification.

CLI surface cleanup

Section titled “CLI surface cleanup”
  • --ollama-host and --no-network are per-command flags on the commands that actually use them, instead of globals cluttering every help screen.
  • Deprecated and hidden (still functional): trial/upgrade (canopy license prints the trial/pricing URLs), cache init (→ canopy setup --only cache), ingest git (→ canopy index auto-ingests).
  • The model command left customer builds: model provisioning is setup --only embedding, offline bundle install is setup --bundle-path.
  • Air-gapped builds: the exact ship combination compiles clean again, and the offline embedding-bundle install lands the Ollama binary and its inference libraries.

Proof

Section titled “Proof”
  • The benchmark report is the spine: 0.932 vs 0.530 correctness (+76%) and −69% tokens on a 270-question, 3-repo library suite; 0.923 vs 0.872 and −80% tokens on the Cal.com cross-layer app corpus — measured cold, graded against ground truth that exists independently of Canopy.