Stacklit

108,000 lines of code. 4,000 tokens of index.

One command makes any repo AI-agent-ready. No server, no setup.

Install and run

npx stacklit init

That is it. Downloads the binary, scans your codebase, generates the index, opens the visual map. One command.

Other install options:

npm install -g stacklit              # install globally, then run: stacklit init
go install github.com/glincker/stacklit/cmd/stacklit@latest

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

What happens when you run it

$ stacklit init
[stacklit] found 342 files
[stacklit] parsed 342 files (0 errors)
[stacklit] done in 89ms -- wrote stacklit.json, DEPENDENCIES.md, stacklit.html

Opening visual map...

Three files appear in your project:

File	What it is	Commit it?
stacklit.json	Codebase index for AI agents	Yes
DEPENDENCIES.md	Mermaid dependency diagram	Yes (renders on GitHub)
stacklit.html	Interactive visual map (4 views)	No (gitignored, regenerates)

git add stacklit.json DEPENDENCIES.md
git commit -m "add stacklit codebase index"

Done. Every AI agent that opens this repo can now read stacklit.json instead of scanning files.

Why

AI coding agents burn most of their context window figuring out where things live. Reading one large file to find a function signature costs thousands of tokens. Five agents on the same repo each rebuild the same mental model from scratch.

Without stacklit: Agent reads 8-12 files. ~400,000 tokens. 45 seconds before writing a line.

With stacklit: Agent reads stacklit.json. ~4,000 tokens. Knows the structure instantly.

Token efficiency (measured on real projects)

Project	Language	Lines of code	Index tokens
Express.js	JavaScript	21,346	3,765
FastAPI	Python	108,075	4,142
Gin	Go	23,829	3,361
Axum	Rust	43,997	14,371

See examples/ for full outputs.

What is in stacklit.json

{
  "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"
  }
}

Modules, dependencies, exports with signatures, type definitions, git activity heatmap, framework detection, and hints for where to add features and how to run tests.

Set up your AI tools

Claude Code

Add to your project's CLAUDE.md:

Read stacklit.json before exploring files. Use modules to locate code, hints for conventions.

Claude Desktop / Cursor (MCP)

Add to your MCP config:

{
  "mcpServers": {
    "stacklit": {
      "command": "stacklit",
      "args": ["serve"]
    }
  }
}

This starts the MCP server with 7 tools: get_overview, get_module, find_module, list_modules, get_dependencies, get_hot_files, get_hints.

Any other agent

stacklit.json is a plain JSON file. Any tool that reads files can use it.

Keep it updated

stacklit init --hook

Installs a git hook that regenerates the index on every commit. Uses Merkle hashing to skip regeneration when only docs or configs changed.

Other ways to keep it fresh:

stacklit generate          # manual regeneration
stacklit generate --quiet  # silent (for scripts/CI)
stacklit diff              # check if the index is stale

GitHub Action for auto-updates

name: Update stacklit index
on:
  push:
    branches: [main]
    paths-ignore: ['stacklit.json', 'DEPENDENCIES.md', '**.md']

jobs:
  stacklit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.25'
      - run: go install github.com/glincker/stacklit/cmd/stacklit@latest
      - run: stacklit generate --quiet
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update stacklit index"
          file_pattern: "stacklit.json DEPENDENCIES.md"

Visual map

stacklit view opens the interactive HTML. Four views:

• Graph -- Force-directed dependency map. Click a node to see 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.

11 languages via tree-sitter

Language	Extracts
Go	imports, exports with signatures, struct fields, interface methods
TypeScript/JS	imports (ESM, CJS, dynamic), classes, interfaces, type aliases
Python	imports, classes with methods, type hints, decorators
Rust	use/mod/crate, pub items with generics, trait methods
Java	imports, public classes, method signatures with types
C#	using directives, public types, method signatures
Ruby	require, classes, modules, methods
PHP	namespace use, classes, traits, public methods
Kotlin	imports, classes, objects, functions
Swift	imports, structs, classes, protocols
C/C++	includes, functions, structs, typedefs

Any other language gets basic support (line count + language detection).

All CLI commands

stacklit init                    # scan, generate, open HTML
stacklit init --hook             # also install git post-commit hook
stacklit init --multi repos.txt  # polyrepo: scan multiple repos
stacklit generate                # regenerate from current source
stacklit view                    # regenerate HTML, open in browser
stacklit diff                    # check if index is stale
stacklit serve                   # start MCP server

Configuration (stacklit.toml)

ignore = ["vendor/", "generated/"]
max_depth = 3

[output]
json = "stacklit.json"
mermaid = "DEPENDENCIES.md"
html = "stacklit.html"

Compared to alternatives

	Stacklit	Repomix	Aider repo-map	Codebase Memory MCP
Output	~4k token index	500k+ token dump	Ephemeral text	SQLite DB
Committed to repo	Yes	Too large	No	No
Dependency graph	Yes	No	Yes	Yes
Visual output	HTML (4 views)	No	No	No
MCP server	Yes (7 tools)	No	No	Yes
Monorepo aware	Yes	No	No	No
Languages	11 (tree-sitter)	N/A	Many	66
Runtime needed	No	No	Yes (Python)	Yes (C server)

Monorepo support

Auto-detects: pnpm, npm, yarn workspaces, Go workspaces, Turborepo, Nx, Lerna, Cargo workspaces, and convention directories (apps/, packages/, services/).

Contributing

make build   # build binary
make test    # run all tests

License

MIT