crowl

README

Crowl

AI-native, commit-driven knowledge graph for source code. Built on git, MIT-licensed.

Crowl lets developers and AI agents navigate a codebase across structure, dependencies, and history — composing static graph queries with a temporal layer (drift, blame, why, as-of, history) that persists across sessions.

Five languages supported out of the box: Go, TypeScript, Python, Java, Rust. One unified tree-sitter pipeline does symbols, edges, type inference, and cross-file call resolution; Go gets an additional go/types-based pass for cross-package interface satisfaction.

Quick start

# Build
go build -o crowl ./cmd/crowl

# Index a repo (Go / TypeScript / Python / Java / Rust all picked up)
./crowl analyze --repo /path/to/repo

# Look up a symbol at HEAD
./crowl query --repo /path/to/repo 'github.com/foo/bar.User.Save'

# Impact (upstream callers, blast radius)
./crowl impact --repo /path/to/repo 'github.com/foo/bar.User.Save'

# Blame (commits that touched this symbol)
./crowl blame --repo /path/to/repo 'github.com/foo/bar.User.Save'

# Why (chronological narrative — commits + messages + authors)
./crowl why --repo /path/to/repo 'github.com/foo/bar.User.Save'

# Drift (what changed since a historical commit)
./crowl drift --repo /path/to/repo --since <sha>

# History (lineage chain across renames)
./crowl history --repo /path/to/repo 'github.com/foo/bar.User.Save'

# Repo summary
./crowl status --repo /path/to/repo

# MCP stdio server (point your AI client at this command)
./crowl mcp --repo /path/to/repo

State lives at ~/.crowl/index/<repo-id>.db (SQLite). Repo identity defaults to a slug of git remote origin, falling back to local_<root-commit-prefix>. Override with --name <alias>.

Languages

All 5 languages get the same edge surface: Contains, HasMethod, HasField, Implements, Extends, Calls, Returns, Accepts. The tree-sitter pipeline does the heavy lifting; Go gets an extra go/types post-pass for cross-package interface satisfaction.

Language	Notes
Go	Full coverage. go/types post-pass adds cross-package Implements edges. Switch to --extractor=types for maximum call-resolution precision.
TypeScript	.ts and .tsx. Module-path FQNs derived from file path.
Python	PEP 484 annotations + walk-and-fixpoint for unannotated locals. __init__.py-bounded module paths.
Java	Package-aware FQNs from package x.y.z; declarations.
Rust	::-separated FQNs. Trait + impl heritage edges.

Extractor backends

--extractor=	What runs
treesitter (default)	Unified tree-sitter pipeline for all 5 languages, plus go/types Implements post-pass for Go
types	Legacy go/types extractor for Go (richer call-resolution precision); per-language tree-sitter for TS/Python; Java/Rust unsupported in this mode

MCP tools (for AI agents)

crowl mcp exposes 9 tools: crowl_query_symbol, crowl_neighbors, crowl_impact, crowl_blame, crowl_history, crowl_as_of, crowl_list, crowl_drift, crowl_why.

Build

crowl builds as a single binary. The default build pulls in smacker/go-tree-sitter for the unified extraction pipeline (CGo). Tree-sitter grammars for Go, TypeScript, Python, Java, and Rust are all bundled — no per-language tooling installs required.

Running the test suite

go test ./... -count=1
# Or the full local gate (matches what CI runs):
make verify

Engineering guidelines

See CLAUDE.md — behavioral guidelines for working on this code (think before coding, simplicity first, surgical changes, goal-driven execution, plus 13 Crowl-specific Go rules).

See CONTRIBUTING.md for the contributor workflow: prerequisites, make verify, what each gate enforces.

License

MIT. No CLA. See LICENSE.