stacklit

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:

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)

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

One command (recommended)

stacklit setup

Auto-detects Claude Code, Cursor, and Aider. For each:

• Injects a compact ~250-token codebase map into the tool's config file
• Configures MCP server integration
• Installs a git hook to keep the map fresh on every commit

Or configure a specific tool:

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

Compact navigation map

stacklit derive         # print to stdout

Generates a ~250-token navigation map 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

Manual setup

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

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

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

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

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
stacklit derive                  # print compact nav map (~250 tokens)
stacklit derive --inject claude  # inject map into CLAUDE.md
stacklit setup                   # auto-configure all detected AI tools
stacklit setup claude            # configure Claude Code + MCP
stacklit setup cursor            # configure Cursor + MCP

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

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

Compared to alternatives

Monorepo support

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

Documentation

• USAGE.md -- full usage guide, command reference, MCP tools, configuration options, reading the index
• SKILL.md -- instructions for AI agents on how to use stacklit.json
• examples/ -- real stacklit.json outputs from Express.js, FastAPI, Gin, Axum

Contributing

make build   # build binary
make test    # run all tests

License

MIT