Stacklit is a good candidate for rescue because the original article pointed at a real pain: coding agents waste time and context learning repo shape. The draft failed because it sounded like a generic token-savings post and did not explain the operating contract that makes Stacklit useful.
The better article is narrower. Stacklit scans a repo, writes stacklit.json, writes a Mermaid DEPENDENCIES.md, and generates a local HTML map. The JSON is the key artifact. It gives agents modules, dependencies, exports, types, git activity, and hints before they start reading files. For Claude Code and Codex users, the value is not that an agent never reads source. The value is that its first read can be a reviewed map instead of a random grep tour.
The map is the product
The README's strongest adoption path is concrete: run npx stacklit init, review the generated files, commit stacklit.json and DEPENDENCIES.md, and leave stacklit.html as a local regenerated view. That commit policy matters. It turns repo orientation into a shared artifact that every agent session can read, not a private mental model rebuilt in every chat.
A good article should therefore stop saying only that Stacklit saves tokens. The more durable claim is that it changes the first step of agent work. Instead of asking Claude Code to inspect directories until it has a rough picture, ask it to read the map, identify the likely module, then open the few source files that matter.
What actually goes into stacklit.json
The schema shows why the file is more than a directory tree. It includes project metadata, language and framework detection, entrypoints, key directories, module records, dependency edges, most-depended modules, isolated modules, git hot files, and hints such as test command and where to add a feature. A module can include purpose, language, files, line count, file list, exports, type definitions, dependencies, dependents, and activity.
That is enough for navigation and blast-radius triage. It is not enough for correctness. If the map says internal/auth is highly depended on, the agent should become more careful, not more confident. Stacklit should shorten the path to the right files; it should not replace reading those files before editing.
The measured examples are useful, but frame them correctly
The project-maintained examples claim compact indexes for real repositories: Express, FastAPI, Gin, and Axum. The FastAPI example is the headline-friendly one: 108,075 lines represented by a 4,142-token full index, with a compact map around 280 tokens in the examples gallery. Those numbers justify preserving the topic.
But a publication-grade article should identify the evidence as Stacklit's own example corpus, not an independent benchmark. The practical question is still clear: if agents repeatedly burn context discovering a repo, a maintained structural index can be cheaper than repeated full exploration. The cost only pays back if the index stays fresh.
Use it as the first-read rule for Claude Code
Stacklit ships a SKILL.md that states the operating rule plainly: when stacklit.json exists at the repo root, read it before reading source files. The skill tells agents to use modules for file selection, dependencies for blast radius, most_depended for risky modules, git activity for change hotspots, and hints for feature placement and test commands.
That is a good Claude Code habit. Add a short rule to CLAUDE.md after running setup: read stacklit.json first, use it to choose files, then verify assumptions in source. This is not about banning rg. It is about reducing blind rg when the repo already contains a maintained map.
Setup should be a small reviewed commit
A safe first rollout looks like this:
npx stacklit init
git diff -- stacklit.json DEPENDENCIES.md
git add stacklit.json DEPENDENCIES.md
git commit -m "add stacklit codebase index"
stacklit setup claude
stacklit diffReview the generated JSON before wiring it into agent instructions. Check that entrypoints, modules, test command, and most-depended paths make sense. If the repo has generated folders, vendor directories, or build outputs, add .stacklitrc.json ignores before committing. A bad map committed once can become a bad instruction repeated by every agent.
MCP is optional, not the baseline
stacklit serve exposes MCP tools such as get_overview, get_module, find_module, list_modules, get_dependencies, get_hot_files, and get_hints. That is useful when an agent runtime supports MCP and wants targeted queries instead of reading the whole JSON file.
Still, the baseline value is the plain committed file. A repo can benefit from stacklit.json even when MCP is unavailable. For Codex-style workflows, that portability is important: the same map can guide Claude Code, Cursor, Aider, Copilot instructions, and any agent that can read files. MCP should improve ergonomics, not become a new required service.
Freshness is the failure mode
The main risk is stale structure. Stacklit addresses this with stacklit init --hook, stacklit generate, stacklit generate --quiet, stacklit diff, a GitHub Action, and a Merkle hash in the index pipeline. The hook implementation regenerates quietly after commits and stages stacklit.json plus DEPENDENCIES.md. The action can generate and auto-commit the same files in CI.
That gives teams options, but it also creates ownership questions. Who accepts generated-file churn? Does CI fail when the map is stale, or does it push updates automatically? Are generated maps reviewed in feature PRs? If those questions are ignored, Stacklit can become another stale artifact agents trust too much.
Compare it to dumpers and graph servers
The comparison document is useful because it gives Stacklit a clear category. Full-content dumpers such as Repomix or files-to-prompt are simple and work well for small one-shot prompts, but they push far more text into the model. Knowledge graph MCP servers can offer richer queries, but they require a running service. Aider's repo-map is strong inside Aider, but less portable as a committed cross-tool artifact.
Stacklit sits in the middle: a static structural index by default, optional MCP server when the environment supports it, and a visual map for humans. That makes it a good fit for teams using multiple coding agents on the same repo.
Where to use it
Use Stacklit when a repo is large enough that the first five minutes of every agent session look the same: list files, inspect package config, search for handlers, read tests, infer entrypoints, and ask where a feature belongs. It is especially useful in monorepos, framework-heavy projects, or repos touched by multiple agents.
Skip it for small repos where the map adds more generated artifact management than value. Also skip it when the team will not enforce freshness. A wrong map is worse than no map because it gives the agent a confident first mistake.
A better verdict for the rescued article
Stacklit deserves publication because it turns codebase orientation into an artifact that can be committed, reviewed, queried, and kept fresh. That is directly useful for Claude Code and Codex workflows. The old article was right that token cost matters, but the stronger editorial angle is workflow governance: what should an agent read first, how should the map be maintained, and when should the agent fall back to source?
The answer is practical. Let Stacklit narrow the search, never let it replace verification, and make freshness a CI or hook rule before agents depend on it.
Save Stacklit as a tool review. It is valuable when stacklit.json becomes a reviewed first-read artifact for agents; it is risky when teams trust a stale structural map or treat token claims as a substitute for source verification.
Practical takeaway
Run npx stacklit init on one real repo, commit only stacklit.json and DEPENDENCIES.md, add a CLAUDE.md rule that agents read the map before source exploration, and then run stacklit diff after structural changes. If the map is useful after a week, choose a freshness policy: post-commit hook, CI check mode, or reviewed auto-commit. Do not wire stacklit serve into MCP until the committed map is already trusted.