README
¶
canopy
Structural code analysis toolkit powered by gotreesitter. AST-based indexing, search, call graph analysis, security intelligence, architecture governance, and AI agent integration across 206+ languages.
Agent Skill
Agents helping someone use Canopy should read the canonical M31 Labs skill: using-canopy.
Install
go install github.com/odvcencio/canopy/cmd/canopy@latest
Quickstart
# Build a structural index
canopy index build .
# Search for symbols
canopy search refs ParseConfig .
# Check code quality (CI gate)
canopy analyze check --max-cyclomatic 30
# Full executive report
canopy analyze report --format markdown
# Run MCP server for AI agents
canopy mcp --root .
Current Release
v0.16.2 upgrades gotreesitter to v0.19.1, carrying the latest pure-Go parser, query, compatibility, and grammar fixes into Canopy indexing. The current release line keeps the large-repo safeguards from v0.16.1: index walks prune ignored directories before descent with ParsePolicy.ShouldSkipDir, direct full-file parses use gotreesitter's concurrency-safe ParserPool, and unsupported/tagless grammars are skipped before parsing. CANOPY_INDEX_GC_EVERY is available for constrained containers. Call graph roots can also be narrowed with --file or path/to/file.go:Name when multiple definitions share a name.
Commands
Index — Build and manage structural indexes
| Command | Description |
|---|---|
canopy index build [path] |
Build/incrementally update index with watch mode |
canopy index map |
Structural table-of-contents for indexed files |
canopy index files |
List files with density filters and sorting |
canopy index stats |
Codebase metrics: symbol counts, language breakdown |
canopy index diff |
Compare structural changes between two snapshots |
canopy index errors |
Show parse errors from indexing |
canopy index validate |
Validate index integrity |
canopy index export |
Export index to portable .canopyindex file for federation |
canopy index import |
Load and summarize exported indexes |
Search — Find symbols, references, and patterns
| Command | Description |
|---|---|
canopy search grep |
Structural selector queries (e.g. function_definition[name=/^Test/]) |
canopy search refs |
Find references by symbol name or regex |
canopy search query |
Raw tree-sitter S-expression queries |
canopy search scope |
Resolve symbols in scope at file + line |
canopy search context |
Pack focused context for agent token budgets. --concept for concept-aware packing |
canopy search symbols |
Search symbols by pattern |
canopy search imports |
Analyze import patterns |
Graph — Call graph, dependency, and coverage analysis
| Command | Description |
|---|---|
canopy graph calls |
Traverse call graph edges from matching roots |
canopy graph dead |
List callable definitions with zero incoming references |
canopy graph deps |
Import dependency graph with cycle detection (--cycles) |
canopy graph bridge |
Map cross-component dependency bridges |
canopy graph impact |
Blast radius via reverse call graph |
canopy graph testmap |
Map test functions to implementations |
canopy graph fanin |
Rank functions by incoming call count |
canopy graph unresolved |
Show unresolved call references |
canopy graph drift |
Compare dependency graph between two git refs |
canopy graph services |
Repo-to-repo dependency map from federated indexes |
Analyze — Quality, complexity, security, and governance
| Command | Description |
|---|---|
canopy analyze check |
CI quality gate with configurable thresholds. --base for diff-aware PR filtering. --format sarif for GitHub Advanced Security |
canopy analyze boundaries |
Module boundary enforcement from .canopyboundaries. --format sarif |
canopy analyze complexity |
Per-function cyclomatic, cognitive, nesting, fan-in/out metrics |
canopy analyze hotspot |
Code hotspots from git churn + complexity + centrality |
canopy analyze lint |
Structural lint with built-in rules, query patterns, and secrets detection. --format sarif |
canopy analyze capa |
Capability detection with MITRE ATT&CK mapping |
canopy analyze reachability |
Supply chain analysis: does package X reach capability Y? |
canopy analyze licenses |
Dependency license detection with SPDX matching and deny rules |
canopy analyze similarity |
Find similar functions between codebases |
canopy analyze duplication |
Detect code duplication |
canopy analyze report |
Executive summary: complexity, architecture, security, dead code, hotspots. --by-team for CODEOWNERS breakdown |
canopy analyze review |
Aggregated PR review: complexity delta, boundary violations, new capabilities, blast radius |
canopy analyze trends |
Track quality metrics over time (record / show) |
Transform — Code transformations and output generation
| Command | Description |
|---|---|
canopy transform refactor |
AST-aware declaration renames with cross-package callsite updates |
canopy transform chunk |
AST-boundary chunks for RAG/indexing. --format embeddings for vector DB |
canopy transform sbom |
CycloneDX 1.5 SBOM with optional capability enrichment |
canopy transform yara |
Generate YARA rules from structural analysis |
canopy transform normalize |
Normalize decompiler output |
Other
| Command | Description |
|---|---|
canopy init |
Guided project setup: generates .canopyignore, .canopygenerated, .canopyboundaries |
canopy init ci |
Generate GitHub Actions workflow for CI quality checks |
canopy mcp |
MCP stdio server exposing 30+ tools to AI agents (Claude, Cursor, VS Code) |
Configuration Files
| File | Purpose |
|---|---|
.canopyignore |
Gitignore-style patterns to exclude files from indexing |
.canopygenerated |
Declare generated file patterns with named generators |
.canopyboundaries |
Module boundary rules (allow/deny import relationships) |
.canopylint |
Lint thresholds, scoped overrides, package-level rules, ignore rules, license deny rules |
.canopyboundaries example
# pkg/model has no internal dependencies
module pkg/model allow -
# pkg/index can only import these packages
module pkg/index allow pkg/model, pkg/lang, pkg/generated
# internal packages can use any pkg but not cross-import
module internal/* allow pkg/*
module internal/* deny internal/*
.canopylint example
# Override default thresholds
cyclomatic > 35 -> warn "function too complex"
cognitive > 60 -> warn "hard to reason about"
# Scoped rules
fan_out > 10 in pkg/* -> warn "high fan-out"
# Package-level rules
package import_depth > 5 -> error "dependency chain too deep"
package exported_symbols > 50 in pkg/* -> warn "API surface too large"
package no_import_cycles -> error "import cycle detected"
# Ignore specific functions
ignore cyclomatic in generated/
# License enforcement
license deny GPL-3.0, AGPL-3.0 -> error "copyleft license not permitted"
Global Flags
| Flag | Description |
|---|---|
--include-generated |
Include generated files in output (excluded by default) |
--generator <name> |
Filter to specific generator (e.g. protobuf, human) |
--federation <dir> |
Directory of .canopyindex files for cross-repo analysis |
Multi-Repo Federation
Analyze across multiple repositories without a central server:
# In each repo's CI:
canopy index build . && canopy index export -o myrepo.canopyindex
# Collect all .canopyindex files, then:
canopy graph services --federation ./indexes/
canopy search refs "AuthService" --federation ./indexes/
canopy graph dead --federation ./indexes/
CI Integration
Generate a GitHub Actions workflow:
canopy init ci
This creates .github/workflows/canopy-check.yml that runs quality checks on PRs with SARIF upload for inline annotations.
Manual SARIF integration:
canopy analyze check --base origin/main --format sarif > results.sarif
Track metrics over time:
canopy analyze trends record # append current metrics to .canopy/trends.jsonl
canopy analyze trends show # display trend summary with deltas
MCP Server
The MCP stdio server exposes 30+ structural analysis tools to AI agents via JSON-RPC.
canopy mcp --root /path/to/repo
canopy mcp --root /path/to/repo --allow-writes # enable refactoring tools
Client setup
Claude Desktop / Claude Code / Cursor / VS Code:
{
"mcpServers": {
"canopy": {
"command": "canopy",
"args": ["mcp", "--root", "/path/to/repo"]
}
}
}
Key MCP tools
| Tool | Description |
|---|---|
gts_guardrails |
File-level advisory: generated status, complexity, fan-in warnings. Call before editing |
gts_review |
Aggregated PR review for changed files |
gts_reachability |
Supply chain capability analysis |
gts_boundaries |
Module boundary enforcement |
gts_report |
Executive summary of all analyses |
gts_callgraph |
Call graph traversal |
gts_dead |
Dead code detection |
gts_impact |
Blast radius computation |
gts_context |
Token-budgeted context packing |
gts_grep |
Structural selector search |
Selector Syntax
Used by canopy search grep and gts_grep:
<kind>[filter1,filter2,...]
Examples:
function_definition[name=/^Test/]method_definition[receiver=/Service/,signature=/Serve/]*[file=/handlers\/.go$/,start>=20,end<=200]
Filters: name, signature, receiver, file (regex); start, end, line (numeric comparisons).
Language Support
206+ languages via gotreesitter grammars including Go, Python, JavaScript/TypeScript, Java, C/C++, Rust, C#, Ruby, PHP, Swift, Kotlin, Scala, SQL, HTML/CSS, YAML, JSON, Terraform, Dockerfile, and many more.
Scope resolution (symbol-in-scope at file+line): Go, Python, TypeScript.
License
See LICENSE for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
canopy
command
|
|
|
canopyls
command
|
|
|
internal
|
|
|
bridge
Package bridge detects cross-component dependency edges between top-level directory groups in a codebase.
|
Package bridge detects cross-component dependency edges between top-level directory groups in a codebase. |
|
chunk
Package chunk splits source files into AST-boundary chunks with token budget estimation for LLM context windows.
|
Package chunk splits source files into AST-boundary chunks with token budget estimation for LLM context windows. |
|
contextpack
Package contextpack builds focus-aware code context around a source line, with optional semantic expansion via call graphs.
|
Package contextpack builds focus-aware code context around a source line, with optional semantic expansion via call graphs. |
|
deps
Package deps analyzes import dependency graphs at the package or file level from a structural index.
|
Package deps analyzes import dependency graphs at the package or file level from a structural index. |
|
federation
Package federation loads and merges exported structural indexes from multiple repositories.
|
Package federation loads and merges exported structural indexes from multiple repositories. |
|
files
Package files lists and filters indexed source files by language, symbol count, and other structural density metrics.
|
Package files lists and filters indexed source files by language, symbol count, and other structural density metrics. |
|
lint
Package lint evaluates structural linting rules and tree-sitter query patterns against a parsed index.
|
Package lint evaluates structural linting rules and tree-sitter query patterns against a parsed index. |
|
mcp
Package mcp exposes canopy tools as an MCP stdio server for AI agent integration via JSON-RPC.
|
Package mcp exposes canopy tools as an MCP stdio server for AI agent integration via JSON-RPC. |
|
reachability
Package reachability answers whether a package transitively reaches sensitive capabilities (process execution, network access, file I/O, etc.) by walking the cross-reference call graph forward from package roots.
|
Package reachability answers whether a package transitively reaches sensitive capabilities (process execution, network access, file I/O, etc.) by walking the cross-reference call graph forward from package roots. |
|
scope
Package scope resolves symbols visible at a given source line using tree-sitter AST traversal.
|
Package scope resolves symbols visible at a given source line using tree-sitter AST traversal. |
|
stats
Package stats aggregates codebase metrics from a structural index: symbol kinds, language distribution, and file density.
|
Package stats aggregates codebase metrics from a structural index: symbol kinds, language distribution, and file density. |
|
pkg
|
|
|
boundaries
Package boundaries provides architecture boundary enforcement through a simple DSL.
|
Package boundaries provides architecture boundary enforcement through a simple DSL. |
|
complexity
Package complexity provides AST-based complexity analysis for functions across 206 languages using gotreesitter.
|
Package complexity provides AST-based complexity analysis for functions across 206 languages using gotreesitter. |
|
coupling
Package coupling computes package-level structural health metrics from a code index and cross-reference graph.
|
Package coupling computes package-level structural health metrics from a code index and cross-reference graph. |
|
feeds
Package feeds defines the FeedProvider interface and the FeedEngine that orchestrates multiple feeds enriching a shared scope graph.
|
Package feeds defines the FeedProvider interface and the FeedEngine that orchestrates multiple feeds enriching a shared scope graph. |
|
feeds/compiler
Package compiler implements a feed that runs language-specific compilers and harvests diagnostics into the scope graph.
|
Package compiler implements a feed that runs language-specific compilers and harvests diagnostics into the scope graph. |
|
feeds/parser
Package parser implements the parser feed, which builds scope graphs from source files using gotreesitter and per-language scope rules.
|
Package parser implements the parser feed, which builds scope graphs from source files using gotreesitter and per-language scope rules. |
|
feeds/proxyfeed
Package proxyfeed implements a feed that harvests type information from backend LSP responses and enriches the scope graph.
|
Package proxyfeed implements a feed that harvests type information from backend LSP responses and enriches the scope graph. |
|
feeds/vcs
Package vcs implements a VCS feed that enriches scope graph definitions with authorship and change history from graft or git.
|
Package vcs implements a VCS feed that enriches scope graph definitions with authorship and change history from graft or git. |
|
generated
Package generated detects machine-generated source files using filename patterns and header markers from a built-in registry of code generators.
|
Package generated detects machine-generated source files using filename patterns and header markers from a built-in registry of code generators. |
|
hotspot
Package hotspot detects code hotspots by combining git churn, complexity, and call graph centrality.
|
Package hotspot detects code hotspots by combining git churn, complexity, and call graph centrality. |
|
ignore
Package ignore implements gitignore-style pattern matching for filtering file paths.
|
Package ignore implements gitignore-style pattern matching for filtering file paths. |
|
impact
Package impact computes the blast radius of changed symbols by walking the reverse call graph.
|
Package impact computes the blast radius of changed symbols by walking the reverse call graph. |
|
index
Package index builds and caches structural indexes by walking source trees and parsing files with registered language parsers.
|
Package index builds and caches structural indexes by walking source trees and parsing files with registered language parsers. |
|
lang
Package lang defines the Parser interface for language-specific source file parsing.
|
Package lang defines the Parser interface for language-specific source file parsing. |
|
lang/treesitter
Package treesitter implements the lang.Parser interface using gotreesitter for multi-language structural parsing.
|
Package treesitter implements the lang.Parser interface using gotreesitter for multi-language structural parsing. |
|
model
Package model defines the core data types for structural code indexing: Symbol, Reference, FileSummary, and Index.
|
Package model defines the core data types for structural code indexing: Symbol, Reference, FileSummary, and Index. |
|
proxy
Package proxy manages backend LSP server processes and routes requests.
|
Package proxy manages backend LSP server processes and routes requests. |
|
query
Package query implements a selector DSL for matching symbols by kind, name, signature, receiver, file, and line range.
|
Package query implements a selector DSL for matching symbols by kind, name, signature, receiver, file, and line range. |
|
refactor
Package refactor performs AST-aware declaration renaming with optional cross-package callsite updates.
|
Package refactor performs AST-aware declaration renaming with optional cross-package callsite updates. |
|
risk
Package risk computes composite risk scores per function and per package by combining complexity, coupling (fan-out), git churn, and test coverage into a single prioritised score.
|
Package risk computes composite risk scores per function and per package by combining complexity, coupling (fan-out), git churn, and test coverage into a single prioritised score. |
|
sarif
Package sarif provides a minimal SARIF 2.1.0 encoder for canopy analysis output.
|
Package sarif provides a minimal SARIF 2.1.0 encoder for canopy analysis output. |
|
scope
Package scope provides the scope graph data model for the canopyls LSP server.
|
Package scope provides the scope graph data model for the canopyls LSP server. |
|
smells
Package smells detects multi-signal structural code smells by combining coupling, complexity, type metrics, and cross-reference data.
|
Package smells detects multi-signal structural code smells by combining coupling, complexity, type metrics, and cross-reference data. |
|
socket
Package socket provides a Unix socket server for CLI client queries against the running canopyls LSP server's enriched scope graph.
|
Package socket provides a Unix socket server for CLI client queries against the running canopyls LSP server's enriched scope graph. |
|
structdiff
Package structdiff compares two structural indexes to detect added, removed, and modified symbols and imports.
|
Package structdiff compares two structural indexes to detect added, removed, and modified symbols and imports. |
|
testmap
Package testmap maps test functions to implementation functions via structural call graph traversal.
|
Package testmap maps test functions to implementation functions via structural call graph traversal. |
|
typemetrics
Package typemetrics computes per-type structural metrics: field count, interface width, method set size, and nesting depth.
|
Package typemetrics computes per-type structural metrics: field count, interface width, method set size, and nesting depth. |
|
xref
Package xref builds cross-reference graphs from structural indexes, enabling call graph traversal and dead code detection.
|
Package xref builds cross-reference graphs from structural indexes, enabling call graph traversal and dead code detection. |
Click to show internal directories.
Click to hide internal directories.