name: stacklit-navigator description: Use stacklit.json to navigate codebases without burning tokens on file exploration

When to use

At the start of any session on a repo that has stacklit.json at the root. Read it before you read any source files.

Reading the index

# Check if index exists
cat stacklit.json | head -5

The file has these sections:

• project -- repo name, type (single/monorepo), workspaces
• tech -- primary language, language breakdown, frameworks
• modules -- the map: each module's purpose, files, exports, dependencies, activity level
• dependencies.edges -- import relationships between modules
• dependencies.most_depended -- the modules everything depends on (touch carefully)
• hints -- where to add features, how to run tests, env vars to set

How to use each section

Finding code: Look up the module in modules by name. The purpose field tells you what it does. The file_list tells you exactly which files to read. Skip everything else.

Understanding structure: Check depends_on and depended_by to see how a module connects to the rest. If you need to change something in src/auth, check depended_by to know what might break.

Knowing what changed recently: The activity field (high/medium/low) tells you how actively a module is being worked on. git.hot_files lists the most-changed files in the last 90 days.

Adding a feature: Read hints.add_feature first. It tells you which directory to create files in and which files to update.

Running tests: Check hints.test_command.

What not to do

• Do not grep across all files when modules tells you which module to look in
• Do not read entire directories to understand the codebase
• Do not re-explore the same repo every session. The index persists across sessions.
• Do not ignore most_depended when planning changes. Those modules have the widest blast radius.

Using the MCP server

If stacklit serve is running as an MCP server, use these tools instead of reading the file:

• get_overview -- full project summary (call this first)
• get_module("src/auth") -- detailed info on one module
• find_module("auth") -- search modules by name
• get_dependencies("src/auth") -- what it imports and what imports it
• get_hot_files -- most-changed files (90 days)
• get_hints -- conventions, test commands, env vars

One get_overview call replaces reading 5-10 files to build context.

Keeping the index fresh

If you have made significant structural changes (new modules, moved files, changed dependencies):

stacklit generate

Use stacklit diff to check if the index is stale before regenerating.

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).

CI / GitHub Action

Use glincker/stacklit-action to keep the index fresh automatically. Auto-commit on push, or gate PRs with check mode:

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

Add permissions: contents: write to the job when using auto-commit mode.

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

Claude Code - add to CLAUDE.md:

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

Claude Desktop / Cursor (MCP) - add to MCP config:

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

MCP server exposes 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

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 export                  # print readable markdown overview
stacklit export -o stacklit.md   # write markdown overview to a file
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"
  }
}

How it compares

Full comparison with 7 tools →

Monorepo support

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

How does Stacklit compare to Repomix?

Repomix concatenates all files into one prompt (50k-500k tokens). Stacklit parses code structure and generates a ~250-token navigation map. Use Repomix for small repos and one-shot chats. Use Stacklit for daily AI-assisted development on larger codebases. See the full comparison.

FAQ

Does Stacklit read my code? Yes, locally. It parses source files with tree-sitter to extract structure (imports, exports, types). No code is sent anywhere unless you use the optional --summary flag (which calls the Claude API).

**What if my language