stacklit

Configuration

Configuration

Create .stacklitrc.json in the project root. The file is optional and every key is optional.

{
  "ignore": ["vendor/", "generated/", "*.pb.go"],
  "max_depth": 3,
  "max_modules": 150,
  "max_exports": 15,
  "output": {
    "json": "stacklit.json",
    "mermaid": "DEPENDENCIES.md",
    "html": "stacklit.html"
  }
}
Key Default Meaning
ignore none Extra gitignore-style patterns to skip, on top of .gitignore and the built-in skips (node_modules, vendor, dist, build, target, .venv, __pycache__ and similar)
max_depth 4 How deep module detection goes in the directory tree
max_modules 200 Above this many modules, deeper ones are collapsed into their parents
max_exports 10 Exports kept per module, taken from the files with the most exports first. Symbols beyond the cap are not in the index, so raise it if lookups by symbol name miss. Env: STACKLIT_MAX_EXPORTS.
max_module_files 30 File names listed per module, files with the most exports first. Env: STACKLIT_MAX_MODULE_FILES.
module_split_files 40 A module with more files than this is split by subdirectory, repeatedly, so one big directory does not hide its files. Env: STACKLIT_MODULE_SPLIT_FILES (-1 turns splitting off).
output.json, output.mermaid, output.html stacklit.json, DEPENDENCIES.md, stacklit.html Output file names. The outputs are excluded from the next scan automatically.
timestamps false Write generated_at. Off by default so a committed index only changes when the code does. Env: STACKLIT_TIMESTAMPS=1.
git_activity false Add git hot and recent files to the index. Off by default for the same reason; opt in with this key or STACKLIT_GIT=1.
steering a Wording of the rules at the top of the generated CLAUDE.md or AGENTS.md block: a, b, c or d (see docs/SESSIONS.md). Env: STACKLIT_STEERING.
crawl_guard (installed mode) Crawl guard mode: off, nudge or redirect. Env: STACKLIT_CRAWL_GUARD.
stats false Append a local usage log of query, slice, explain and impact calls. Env: STACKLIT_STATS=1. Never networked.
map_icons remote remote lets the HTML map request language logos from thesvg.org when you open it. off removes every remote URL and shows letters instead. Env: STACKLIT_MAP_ICONS=off.
cache true On-disk parse cache. STACKLIT_NO_CACHE=1 disables it.
workers CPU count Parser pool size. Env: STACKLIT_WORKERS.
parse_memory_mb 256 Soft cap on the estimated memory of concurrent tree-sitter parses. A single file above the cap still parses, alone. Env: STACKLIT_PARSE_MEMORY_MB (0 disables the cap).
parse_timeout_ms 3000 Wall-clock budget per file for tree-sitter. A file that exceeds it is indexed with line count only and listed in scan.lightweight. Env: STACKLIT_PARSE_TIMEOUT_MS (0 disables).
ts_max_bytes 131072 Files larger than this skip tree-sitter (reason large). Env: STACKLIT_TS_MAX_BYTES (0 disables).
max_line_len 2000 A line longer than this marks the file minified and skips tree-sitter. Env: STACKLIT_MAX_LINE_LEN (0 disables).
skip_generated true Files named .min., .pb., .gen. or marked “generated” / “do not edit” in the first KB skip tree-sitter. Env: STACKLIT_SKIP_GENERATED.
memory_limit_mb 448 Soft Go heap limit during a scan, to keep RSS near the live set. An explicit GOMEMLIMIT wins. Env: STACKLIT_MEMORY_LIMIT_MB (0 disables).

Diagnostics: STACKLIT_TRACE=1 prints files whose parse took over 250 ms; STACKLIT_PPROF=<dir> writes cpu.pprof, heap.pprof and heap-peak.pprof.

| check | none | Architecture rules for stacklit check: forbidden, cycles, max_fan_in, max_fan_out, orphans (see stacklit check) |

A file that is missing, unreadable or invalid JSON is ignored and the defaults are used.

Only files with recognised source extensions are scanned. Directories named test, tests, testdata, fixtures, e2e, bench or benchmarks are left out of the module list, and each module lists up to about 20 file names.

Environment variables

Variable Used by Meaning
STACKLIT_SUMMARY_CMD init --summary Command (split on whitespace) that reads a prompt on stdin and prints the summary. Default: claude -p.
STACKLIT_SUMMARY_TIMEOUT init --summary Timeout in seconds. Default: 120.
STACKLIT_EXPORT_PAGE_TOKENS export --format markdown-wiki, obsidian Token budget per page. Default: 2000.
STACKLIT_EXPORT_MAX_NODES export --format dot, mermaid Node cap, highest degree kept. Default: 300.
STACKLIT_ADAPTER_TIMEOUT_SEC, STACKLIT_ADAPTER_MAX_BYTES, STACKLIT_ADAPTER_MAX_ITEMS ingest --adapter Adapter timeout, output size and item caps. Defaults: 60, 4194304, 5000.
STACKLIT_DIGEST_TOKENS setup, hooks Token cap of the injected digest. Default 500.
STACKLIT_STEERING setup Steering wording variant a, b, c or d.
STACKLIT_CRAWL_GUARD hook crawl off, nudge or redirect. Overrides the crawl_guard config key and the mode the hook was installed with. Default off when nothing sets it.
STACKLIT_CRAWL_REDIRECTS, STACKLIT_CRAWL_FRESH_TTL hook crawl Consecutive redirects per session before the guard stands down (default 2), and seconds a staleness verdict is reused (default 10).
STACKLIT_CRAWL_MAX_DEPTH, STACKLIT_CRAWL_PROMPT_CHARS hook crawl Deepest find -maxdepth or tree -L still treated as narrow (default 1), and longest subagent prompt judged generic (default 600).
STACKLIT_CRAWL_POINTER_MAX_BYTES, STACKLIT_CRAWL_STATE_DAYS hook crawl Largest graph loaded to build an exact pointer (default 8 MiB), and days before session state files are pruned (default 7).
STACKLIT_STATS query, slice, explain, impact 1 logs usage locally, 0 forces it off.
STACKLIT_CACHE_DIR cache, hooks, stats Where the parse cache, session state and usage log live.
STACKLIT_REFRESH_DEBOUNCE_MS, STACKLIT_LOCK_STALE_SEC refresh Debounce before a refresh (default 30) and age at which a lock is treated as abandoned (default 30).
STACKLIT_SUBAGENT_TYPES hook subagent Comma list of agent types that get the digest. Default Explore,Plan.
STACKLIT_SCIP_MAX_BYTES ingest --scip Largest SCIP file read. Default: 512 MiB.

Summary (opt-in)

stacklit init --summary runs the command above with a prompt made of a short instruction plus a JSON snapshot of the index (project, tech, modules with exports and dependencies, entrypoints). No file contents are included. The output is stored under architecture.ai_summary in stacklit.json. If the command fails, a warning is printed and the index is written without a summary. Stacklit itself opens no network connection; whether the command you configure does is up to that command.

Generated from docs/USAGE.md in the repository, the single source of truth.