Stacklit

A committed map of your codebase for AI coding agents. 137 tokens for a 19,500 line Go repo.

CI Release npm version npm downloads Go reference MIT license

stacklit init in a terminal

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

Visual map of a repo Copy-ready prompts for an agent Flow steps through a codebase

## 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

Claude Code  Cursor  Codex  Gemini CLI  GitHub Copilot  Windsurf  Zed  Amp

`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
Go
Python
Python
TypeScript / JSTypeScript / JS
TypeScript / JS
Rust
Rust
Java
Java
C#
C#
Kotlin
Kotlin
Swift
Swift
PHP
PHP
Ruby
Ruby
C
C
C++
C++
Scala
Scala
Dart
Dart
Elixir
Elixir
Lua
Lua
Zig
Zig
Haskell
Haskell
OCaml
OCaml
S
Solidity
**Index only (modules, exports and imports, no call edges)**
Shell
Shell
S
SQL
GDScript
GDScript
Vue / SvelteVue / Svelte
Vue / Svelte
Terraform / HCLTerraform / HCL
Terraform / HCL
P
Protobuf
Clojure
Clojure
R
R
Perl
Perl
Julia
Julia
Objective-C
Objective-C
G
Groovy
Nim
Nim
Erlang
Erlang
F#
F#
Fortran
Fortran
Elm
Elm
PowerShell
PowerShell
Gleam
Gleam
CMake
CMake
M
Makefile
Dockerfile
Dockerfile
YAML / TOML / JSONYAML / TOML / JSONYAML / TOML / JSON
YAML / TOML / JSON
GraphQL
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).