Canopy

canopy

[](https://pkg.go.dev/m31labs.dev/canopy) [](https://github.com/odvcencio/canopy/actions/workflows/ci.yml) [](https://github.com/odvcencio/canopy/actions/workflows/release.yml)

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 m31labs.dev/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 Main

Current main uses gotreesitter v0.45.0 and keeps large-repository indexing bounded by default: the CLI uses a 1 GiB Go soft memory limit when the caller has not supplied one, while index builds use at most two concurrent parse workers and a garbage collection cadence of 32 parsed files. Index walks also prune ignored directories before descent and skip unsupported or tagless grammars before parsing.

The defaults remain tunable for unusual workloads:

• GOMEMLIMIT overrides the Go soft memory limit.
• GTS_MAX_CONCURRENT overrides the parser worker count.
• CANOPY_INDEX_GC_EVERY overrides the collection cadence; set it to 0 to disable forced collections.

Call graph roots can 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 | Filter to specific generator (e.g. protobuf, human) | | --federation | 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:

[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](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: odvcencio
• Source: odvcencio/canopy
• License: MIT
• Homepage: https://m31labs.dev/canopy

Install and usage instructions live in the source repository linked above.