Index Your First Repo

Once Canopy is installed, indexing a repo takes one command.

Basic indexing

cd ~/path/to/your/repo
canopy index .

Expected output:

canopy: indexing /path/to/your/repo (incremental)
canopy: AST index done — 2,104 files indexed, 0 skipped, 0 errors (2,631 ms)
canopy: tip — run with --with-search to also build the full-text search index

The first run is the slow one. Subsequent runs process only changed files and finish in a fraction of the time.

Full index with search and git history

For the best agent experience, also build the full-text search index and ingest git history:

canopy index . --full --with-search --with-git

What each flag adds:

Flag	Enables	Tools unlocked
(none)	AST graph, imports, exports, dependency edges	canopy_trace_imports, canopy_trace_dependents, canopy_check_wiring, canopy_find_cycles
--with-search	Tantivy keyword search index	canopy_search
--with-git	Commit history, blame data	canopy_git_history, canopy_git_blame
--full	Wipes previous index, re-scans everything	—

Tip

Run --full --with-search --with-git for the first index on any new repo. After that, canopy index . (no flags) handles incremental updates fast enough to run on every save if you use canopy serve --watch.

Checking the index

canopy status

Example output:

canopy status — /path/to/your/repo
  Index age:    2 minutes ago
  Files:        2,104 indexed, 0 stale
  Symbols:      18,432
  Import edges: 6,211
  Search:       ready (Tantivy)
  Git history:  ready (847 commits)
  Health:       not run — use `canopy health`

If any layer shows not ready, re-run the corresponding flag.

Run a health check

canopy health

This runs the four built-in checks across your indexed codebase:

• broken_imports — import paths that resolve to no indexed file
• dead_exports — named exports with no known consumers
• circular_deps — import cycles in the dependency graph
• secret_scan — hard-coded API keys, tokens, and credentials

Example output:

canopy health — /path/to/your/repo
  P0 critical:  0
  P1 errors:    2
    dead_exports: src/utils/legacy.ts — export `oldHelper` has 0 consumers
    broken_imports: src/api/client.ts — cannot resolve './helpers/retry'
  P2 warnings:  5
  Info:         12

No findings is ideal. A few P1s in a real codebase is normal. P0s (circular deps that break module loading, or secrets) deserve immediate attention.

Where does the index live?

Canopy stores its index in ~/.canopy/<repo-id>/ — a SHA-1-keyed directory per repo.

~/.canopy/
└── 3a7f9bc2.../          # SHA-1 of the repo root path
    ├── forge.db           # SQLite: AST graph, symbols, imports, health findings
    ├── search/            # Tantivy full-text index (present if --with-search)
    ├── heartbeat.json     # License heartbeat cache
    └── community_usage.json  # Rate limit counters (Community Mode only)

To reset the index for a repo:

canopy index . --full
# or delete the directory manually:
rm -rf ~/.canopy/<repo-id>/

Supported languages

Canopy uses tree-sitter grammars for structural parsing. Supported in v1.4.0:

Language	AST parsing	Import/export edges	Symbol extraction
TypeScript	Yes	Yes	Yes
JavaScript	Yes	Yes	Yes
Python	Yes	Yes	Yes
Rust	Yes	Yes	Yes
Go	Yes	Yes	Yes

Other file types (YAML, JSON, Markdown, etc.) are indexed for full-text search but not AST-parsed. See Concepts: AST Parsing for the tradeoffs.

Next

Connect to Claude Code — add Canopy to your agent’s MCP config.