stacklit-navigator

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.