README
¶
Crowl
AI-native, commit-driven knowledge graph for source code. Built on git, MIT-licensed, single static binary (Go-only mode).
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.
Quick start
# Build
go build -o crowl ./cmd/crowl
# Index a repo (Go / TypeScript / Python all picked up automatically)
./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
| Language | Coverage |
|---|---|
| Go | Full type-aware (Calls, Implements, Returns, Accepts edges via go/types) |
| Python | Declarations + best-effort Calls (AST-only resolution; no cross-module type inference) |
| TypeScript | Declaration-level only |
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 flavors
crowl builds as a single static binary. The Go-only build path uses
no CGo; the default build pulls in smacker/go-tree-sitter for
TypeScript + Python (CGo). For a CGo-free build, fork
cmd/crowl/main.go and import only internal/extract/golang.
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.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
crowl
command
Command crowl is the v0.1 CLI entrypoint.
|
Command crowl is the v0.1 CLI entrypoint. |
|
internal
|
|
|
cli
Package cli wires Pipeline / Query / Store / Extractor / Source into user-facing commands.
|
Package cli wires Pipeline / Query / Store / Extractor / Source into user-facing commands. |
|
core
Package core defines the L0 contracts for Crowl: types, interfaces, hashing, and format version constants.
|
Package core defines the L0 contracts for Crowl: types, interfaces, hashing, and format version constants. |
|
extract
Package extract defines the Extractor interface (FOUNDATION §5).
|
Package extract defines the Extractor interface (FOUNDATION §5). |
|
extract/golang
Package golang implements the Go-language extractor using the standard library (go/parser, go/ast, go/token, go/types) plus golang.org/x/tools/go/packages for module-aware loading.
|
Package golang implements the Go-language extractor using the standard library (go/parser, go/ast, go/token, go/types) plus golang.org/x/tools/go/packages for module-aware loading. |
|
extract/python
Package python implements a Python extractor backed by tree-sitter.
|
Package python implements a Python extractor backed by tree-sitter. |
|
extract/scope
Package scope is the cross-extractor pre-filter that decides whether a file should be considered for symbol extraction.
|
Package scope is the cross-extractor pre-filter that decides whether a file should be considered for symbol extraction. |
|
extract/typescript
Package typescript implements a v0.3 TypeScript extractor backed by tree-sitter.
|
Package typescript implements a v0.3 TypeScript extractor backed by tree-sitter. |
|
lineage
Package lineage implements rename detection for v0.1: body-hash exact match.
|
Package lineage implements rename detection for v0.1: body-hash exact match. |
|
mcp
Package mcp implements a minimal Model Context Protocol server over stdio, exposing the Crowl Query primitives as tools.
|
Package mcp implements a minimal Model Context Protocol server over stdio, exposing the Crowl Query primitives as tools. |
|
migrate
Package migrate forward-migrates record types across format versions.
|
Package migrate forward-migrates record types across format versions. |
|
mutate
Package mutate orchestrates the per-commit mutation flow: extract → diff against parent KC → write CommitWriter → produce KC.
|
Package mutate orchestrates the per-commit mutation flow: extract → diff against parent KC → write CommitWriter → produce KC. |
|
pipeline
Package pipeline orchestrates per-commit processing.
|
Package pipeline orchestrates per-commit processing. |
|
query
Package query implements the L1 read-side primitives over a core.Store.
|
Package query implements the L1 read-side primitives over a core.Store. |
|
source
Package source provides implementations of mutate.SourceProvider — objects that can hand the Mutator a source tree, commit message, and commit metadata for a given git SHA.
|
Package source provides implementations of mutate.SourceProvider — objects that can hand the Mutator a source tree, commit message, and commit metadata for a given git SHA. |
|
store/memory
Package memory implements core.Store entirely in memory.
|
Package memory implements core.Store entirely in memory. |
|
store/sqlite
Package sqlite implements core.Store backed by SQLite (modernc.org/sqlite, pure Go, no CGo).
|
Package sqlite implements core.Store backed by SQLite (modernc.org/sqlite, pure Go, no CGo). |