A committed map of your codebase for AI coding agents. 137 tokens for a 19,500 line Go repo.
Stacklit maps your codebase once and keeps the map fresh. It parses your repo with tree-sitter and writes `stacklit.json`: modules, exports, dependency edges and hints. Commit it, and your coding agent reads a few hundred tokens instead of crawling your files, then uses a few commands (`query`, `slice`, `impact`) to go straight to the right file.
Free and MIT, no paid tier. One Go binary, local and deterministic, no LLM, and the CLI makes no network calls. (The map page can load language icons from thesvg.org; `STACKLIT_MAP_ICONS=off` removes that.)
## Install
```bash
npx stacklit init # scan, write the index, open the map
stacklit setup # wire up the assistants it detects
git add stacklit.json && git commit -m "add stacklit index"
```
Also: `brew install glincker/tap/stacklit`, `npm install -g stacklit`, `go install github.com/glincker/stacklit/cmd/stacklit@latest`, or a binary from [Releases](https://github.com/glincker/stacklit/releases).
## See it
## Output
`stacklit derive` prints a compact map for a prompt (gin v1.10.0, 137 tokens, module list trimmed here):
```
gin | go | 8 modules | 19,537 lines | Gin, GitHub Actions, net/http
test: go test ./... | env: PORT
modules:
binding binding | depends: bytesconv, json
internal/bytesconv bytesconv | depended-by: binding, render, root
render render | depends: bytesconv, json
root root package | depends: binding, bytesconv, json, render
do-not-touch: .github/
```
`stacklit query` returns a token-budgeted slice of the symbol graph (output trimmed here):
```
$ stacklit query "how is the symbol graph built" --budget 600
internal/cli/graphcmds.go
50-63 func buildSymbolGraph(root string, includeTests ...bool) (*graph.SymGraph, error)
calls BuildSymbols E0.95
internal/graph/resolve.go
955-961 func BuildSymbols(root string, files []string, eo ExtractOptions) *SymGraph
```
## What you get
| | |
|---|---|
| Index | `stacklit.json`, a Mermaid diagram (`DEPENDENCIES.md` by default, set with `output.mermaid`) and an interactive `stacklit.html` map |
| Languages | 48 languages and formats indexed; symbol graph for 20 ([list](docs/LANGUAGES.md)) |
| Queries | `query`, `explain`, `impact`, `path`, `hubs`, `slice`, each with a hard `--budget` |
| MCP | `stacklit serve`: 15 tools, or `--profile minimal` for 4 (about 230 tokens of schema) |
| Hooks | git post-commit refresh; optional Claude Code hook that points a grepped identifier to its definition |
| CI | `export` (graphml, cypher, dot, mermaid and more), `check` architecture rules, `status` freshness, `merge-graphs`, a [GitHub Action](https://github.com/glincker/stacklit-action) |
| Deterministic | same repo, same bytes. A committed index only changes when the code does |
| Privacy | no telemetry, no upload. The map loads language logos from thesvg.org unless `STACKLIT_MAP_ICONS=off` ([details](docs/PRIVACY.md)) |
## Assistants
`stacklit setup` sets up 25 assistants, including Aider, Cline, Continue, OpenCode, Roo Code and Kiro, plus a generic `AGENTS.md` (`stacklit setup --list` shows all 26 targets). Anything else can read `stacklit.json` directly.
## Languages
Stacklit indexes 48 languages and formats ([full table](docs/LANGUAGES.md)). Symbol graph and call edges (`query`, `slice`, `impact`) cover 20 of them.
**Symbol graph and call edges (20)**
Go
Python
TypeScript / JS
Rust
Java
C#
Kotlin
Swift
PHP
Ruby
C
C++
Scala
Dart
Elixir
Lua
Zig
Haskell
OCaml
S Solidity
**Index only (modules, exports and imports, no call edges)**
Shell
S SQL
GDScript
Vue / Svelte
Terraform / HCL
P Protobuf
Clojure
R
Perl
Julia
Objective-C
G Groovy
Nim
Erlang
F#
Fortran
Elm
PowerShell
Gleam
CMake
M Makefile
Dockerfile
YAML / TOML / JSON
GraphQL
Anything else gets line counts and language detection.
## Benchmark
Two tests, with different answers. The first, with no model in the loop: six pinned repos in six languages, 58 tasks, tokens as bytes / 4. The derived map is 137 to 1,351 tokens. On 47 where-is-X questions one `stacklit query` with a 1,000 token budget put the right file first on 81% (95% interval 70 to 91) and in the top five on 96%. Grep with a hand written pattern did better, 89% first and 100% in the top five. The 81% was tuned after looking at failures, so treat it as an upper bound. Method and limits: [bench/RESULTS.md](bench/RESULTS.md).
The second is a real agent test, run twice. Round 1: 450 Claude Code sessions (Sonnet, 30 questions, three public repos, plan written before the first run). Stacklit changed how the agent works but **did not lower cost overall**: pooled cost ratio 1.00 [0.93, 1.07], tokens 1.01 [0.92, 1.10]. It used about a third fewer tool calls (0.68 [0.61, 0.77]), a quarter fewer turns (0.77) and over four fifths fewer grep and glob calls (0.18). Answers were right slightly less often (94.0% to 88.0% on the pre-registered grader, 98.0% to 95.3% audited). Cost ratio by repo (below 1 is cheaper, 50 paired sessions each; full tables, method, limits and the claims we do not make are in [bench/agent-ab/RESULTS.md](bench/agent-ab/RESULTS.md)):
| Repo | Size | Cost ratio [95% CI] |
|---|---|---|
| levelrail | about 16,000 files | 0.78 [0.70, 0.86] |
| theauth-go | about 1,300 files | 1.10 [0.98, 1.25] |
| featuredrop | about 400 files | 1.23 [1.14, 1.33] |
**Round 2** (650 more sessions, 40 new questions, four repos, [bench/agent-ab/RESULTS-round2.md](bench/agent-ab/RESULTS-round2.md)) pointed the same way. The 16,000 file repo was cheaper again (0.89 [0.84, 0.96] with the default wording, 0.87 [0.81, 0.93] with the routed wording). The smaller repos cost more: theauth-go 1.10 and 1.05, featuredrop 1.37 and 1.21, theauth (about 2,900 files) 1.61 and 1.42. Pooled over all four repos a session cost more, not less: 1.17 [1.11, 1.24] and 1.09 [1.04, 1.14]. Tool calls were 0.76 of the no Stacklit count and Grep and Glob calls 0.22 and 0.53. Right answers were equal (97.5%, 97.0%, 97.5%). The model had partly memorised featuredrop, which favours the side without Stacklit. So today Stacklit is for very large repos and "where is it" questions, not for small repos.
**When it helps.** Locate and add-feature questions ("where is it", "where does a new thing go") were 12 to 22 percent cheaper, mostly on the large repo. Trace questions cost the same and were right less often. "Who imports X" cost 1.59x [1.47, 1.72] because one exact grep already answers it. Small repos cost more, since the map is overhead there. The strict setup (crawl guard plus strict rules) measured worse and is off by default.
## Docs
[Usage](docs/USAGE.md) | [Languages](docs/LANGUAGES.md) | [FAQ](docs/FAQ.md) | [Privacy](docs/PRIVACY.md) | [Architecture](docs/ARCHITECTURE.md) | [Comparison](docs/COMPARISON.md) | [Roadmap](docs/ROADMAP.md) | [Changelog](CHANGELOG.md) | [Agent skill](skills/stacklit/SKILL.md) | [Brand kit](docs/brand/README.md)
Contributing: [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md). Security reports: [.github/SECURITY.md](.github/SECURITY.md). Questions: [Discussions](https://github.com/glincker/stacklit/discussions).
MIT. See [LICENSE](LICENSE).