stacklit - codebase context for agents in 250 tokens

The pitch on the README is the right one in one line: 108,000 lines of code, 4,000 tokens of index. Stacklit replaces the agent's exploration phase - the part where it reads eight to twelve files trying to figure out where things live - with a structured codebase summary it can swallow in one go.

The shape that distinguishes it from Repomix-style approaches: Repomix concatenates files into one giant prompt (50k–500k tokens). Stacklit parses with tree-sitter and emits a navigation map. The agent learns the structure once; you don't pay the exploration tax on every session.

Quick start

npx stacklit init

That's it. Downloads the binary, scans the repo, generates the index, opens the visual map. Other install paths if you'd rather:

npm install -g stacklit
go install github.com/glincker/stacklit/cmd/stacklit@latest

Or grab a binary from GitHub Releases (macOS, Linux, Windows).

What you commit

Three files appear after init:

Commit the JSON and the dependency diagram and any agent that opens the repo can read them instead of scanning files.

What's in stacklit.json

The index is structured, not narrative. Modules with purposes, dependencies, exports with signatures, type definitions, plus a git activity heatmap and hints for "where do I add a feature" and "how do I run the tests":

{
  "modules": {
    "src/auth": {
      "purpose": "Authentication and session management",
      "files": 8, "lines": 1200,
      "exports": ["AuthProvider", "useSession()", "loginAction()"],
      "depends_on": ["src/db", "src/config"],
      "activity": "high"
    }
  },
  "hints": {
    "add_feature": "Create handler in src/api/, add route in src/index.ts",
    "test_command": "npm test"
  }
}

Activity comes from git history; hints are derived from project conventions. Both compose - "where should I add this feature" plus "what's the test command" is most of the project context an agent actually needs.

Token efficiency on real projects

The README publishes its own measurements:

The Axum number is the outlier - Rust's heavy generics blow up signature output. Most languages settle in the 3-4k range regardless of repo size, which is the property that makes the index feasible to inject into every session.

The 250-token derived map

stacklit derive is the underrated command. It prints an even more compressed navigation map - around 250 tokens - that replaces 3,000-8,000 tokens of agent exploration:

myapp | go | 14 modules | 8,420 lines
entry: cmd/api/main.go | test: go test ./...

modules:
  cmd/api/          entrypoint, routes, middleware
  internal/auth/    jwt, session | depends: store, config
  internal/store/   postgres | depended-by: auth, handler

This is the form to inject into CLAUDE.md, .cursorrules, or .github/copilot-instructions.md. It's small enough to live in every session and dense enough to carry the structural information the agent actually needs.

Setup for AI tools

stacklit setup

Auto-detects Claude Code, Cursor, and Aider. For each tool it injects the ~250-token map into the config file, configures MCP server integration, and installs a git hook to keep the map fresh on every commit.

Per-tool variants exist:

stacklit setup claude   # updates CLAUDE.md + .mcp.json
stacklit setup cursor   # updates .cursorrules + .cursor/mcp.json
stacklit setup aider    # updates .aider.conf.yml

The MCP server (stacklit serve) exposes 7 tools: get_overview, get_module, find_module, list_modules, get_dependencies, get_hot_files, get_hints. That's enough surface for an agent to walk the codebase without ever reading source files for navigation.

Keeping the index fresh

stacklit init --hook        # install git post-commit hook
stacklit generate           # manual regeneration
stacklit generate --quiet   # silent (for scripts/CI)
stacklit diff               # check if the index is stale

The hook uses Merkle hashing to skip regeneration when only docs or configs changed - on a 10k-line repo, an actual regeneration is around 50ms.

For CI, there's a packaged GitHub Action (glincker/stacklit-action):

- uses: actions/checkout@v4
- uses: glincker/stacklit-action@v1        # auto-commit
# or:
- uses: glincker/stacklit-action@v1
  with: { mode: check }                    # fail PR if index is stale

Languages

Tree-sitter coverage with structural extraction (not just line counts):

Go, TypeScript/JavaScript, Python, Rust, Java, C#, Ruby, PHP, Kotlin, Swift, C/C++. Other languages fall back to basic support (line count + language detection) - the module map, dependency graph, and git activity still work, you just lose the export-level signatures.

Visual map

stacklit view opens an interactive HTML with four lenses:

• Graph - force-directed dependency map; click a node for exports, types, files.
• Tree - collapsible directory hierarchy with file and line counts.
• Table - sortable module table with search filter.
• Flow - top-down dependency flow from entrypoints to leaves.

Useful for the human side of the workflow - you onboard a teammate by walking them through the graph view, not by handing them a 3MB README.

How it compares

The README's own comparison table is honest about positioning:

If you only have a small repo and you're doing one-shot chats, Repomix is fine - 50k tokens of full source is genuinely useful when the agent is going to read everything anyway. Stacklit pulls ahead when the repo is larger than that and the same agents come back to it repeatedly.

When to reach for it

• Codebases that are too big to dump but where agents keep re-exploring the same files.
• Multi-agent setups where each agent would otherwise rebuild the same mental model from scratch.
• Long-running agent sessions where saving exploration tokens compounds across turns.
• Onboarding (humans or agents) into an unfamiliar codebase.

When not to

• Tiny codebases (a few thousand lines). The agent can hold the whole thing.
• Highly dynamic codebases that change shape every session - the index will be stale every time.
• Languages outside the tree-sitter list where you specifically need export-level signatures.

Trade-offs

Reads code locally only. The optional --summary flag calls the Claude API to generate module purpose strings; everything else is offline.

Monorepo support is reasonable - auto-detects pnpm, npm, yarn workspaces, Go workspaces, Turborepo, Nx, Lerna, Cargo workspaces, and the standard apps//packages//services/ conventions. stacklit init --multi repos.txt handles the polyrepo case.

MIT licensed. The examples/ directory has full stacklit.json outputs from Express.js, FastAPI, Gin, and Axum, which is the fastest way to evaluate whether the format fits your needs without running it on your own repo first.