Skip to content

Commit 37c2573

Browse files
thegdsksthegdsks
committed
docs: polish README flow, add comprehensive USAGE.md guide
1 parent eff3b92 commit 37c2573

2 files changed

Lines changed: 423 additions & 83 deletions

File tree

‎README.md‎

Lines changed: 112 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -9,31 +9,71 @@ One command makes any repo AI-agent-ready. No server, no setup.
99
[![npm](https://img.shields.io/npm/v/stacklit)](https://www.npmjs.com/package/stacklit)
1010
[![License](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
1111

12-
## Quick start
12+
## Install and run
1313

1414
```bash
1515
npx stacklit init
1616
```
1717

18+
That is it. Downloads the binary, scans your codebase, generates the index, opens the visual map. One command.
19+
20+
Other install options:
21+
22+
```bash
23+
npm install -g stacklit # install globally, then run: stacklit init
24+
go install github.com/glincker/stacklit/cmd/stacklit@latest
25+
```
26+
27+
Or grab a binary from [GitHub Releases](https://github.com/glincker/stacklit/releases) (macOS, Linux, Windows).
28+
1829
![Stacklit demo](demo.gif)
1930

20-
## The problem
31+
## What happens when you run it
32+
33+
```
34+
$ stacklit init
35+
[stacklit] found 342 files
36+
[stacklit] parsed 342 files (0 errors)
37+
[stacklit] done in 89ms -- wrote stacklit.json, DEPENDENCIES.md, stacklit.html
38+
39+
Opening visual map...
40+
```
41+
42+
Three files appear in your project:
43+
44+
| File | What it is | Commit it? |
45+
|------|-----------|------------|
46+
| `stacklit.json` | Codebase index for AI agents | **Yes** |
47+
| `DEPENDENCIES.md` | Mermaid dependency diagram | **Yes** (renders on GitHub) |
48+
| `stacklit.html` | Interactive visual map (4 views) | No (gitignored, regenerates) |
49+
50+
```bash
51+
git add stacklit.json DEPENDENCIES.md
52+
git commit -m "add stacklit codebase index"
53+
```
54+
55+
Done. Every AI agent that opens this repo can now read `stacklit.json` instead of scanning files.
56+
57+
## Why
2158

2259
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.
2360

24-
**Without stacklit:** Agent reads 8-12 files to build context. ~400,000 tokens. 45 seconds before writing a line.
61+
**Without stacklit:** Agent reads 8-12 files. ~400,000 tokens. 45 seconds before writing a line.
2562

26-
**With stacklit:** Agent reads `stacklit.json`. ~4,000 tokens. Knows every module, dependency, and convention instantly.
63+
**With stacklit:** Agent reads `stacklit.json`. ~4,000 tokens. Knows the structure instantly.
2764

28-
## What you get
65+
### Token efficiency (measured on real projects)
66+
67+
| Project | Language | Lines of code | Index tokens |
68+
|---------|----------|---------------|-------------|
69+
| Express.js | JavaScript | 21,346 | 3,765 |
70+
| FastAPI | Python | 108,075 | 4,142 |
71+
| Gin | Go | 23,829 | 3,361 |
72+
| Axum | Rust | 43,997 | 14,371 |
2973

30-
| File | Purpose | Committed? |
31-
|------|---------|------------|
32-
| `stacklit.json` | Machine-readable codebase index | Yes |
33-
| `DEPENDENCIES.md` | Mermaid dependency diagram (renders on GitHub) | Yes |
34-
| `stacklit.html` | Interactive visual map with 4 views | No (gitignored) |
74+
See [examples/](examples/) for full outputs.
3575

36-
### stacklit.json
76+
## What is in stacklit.json
3777

3878
```json
3979
{
@@ -53,61 +93,21 @@ AI coding agents burn most of their context window figuring out where things liv
5393
}
5494
```
5595

56-
### Token efficiency (measured)
57-
58-
| Project | Language | Lines of code | Index tokens |
59-
|---------|----------|---------------|-------------|
60-
| Express.js | JavaScript | 21,346 | 3,765 |
61-
| FastAPI | Python | 108,075 | 4,142 |
62-
| Gin | Go | 23,829 | 3,361 |
63-
| Axum | Rust | 43,997 | 14,371 |
64-
65-
See [examples/](examples/) for real outputs.
66-
67-
### Visual map
68-
69-
![Stacklit visual map](stacklit-og.png)
70-
71-
Four views: **Graph** (force-directed dependency map), **Tree** (collapsible directories), **Table** (sortable modules with search), **Flow** (top-down dependency flow). Self-contained HTML, works offline.
72-
73-
## How it works
74-
75-
1. **Walk** -- Find source files, respect `.gitignore`
76-
2. **Parse** -- Extract imports, exports, types via tree-sitter AST (11 languages)
77-
3. **Graph** -- Group files into modules, resolve dependencies
78-
4. **Detect** -- Identify monorepo structure, frameworks, entrypoints
79-
5. **Git** -- 90-day commit history for file activity heatmap
80-
6. **Render** -- Write JSON, Mermaid, and HTML
96+
Modules, dependencies, exports with signatures, type definitions, git activity heatmap, framework detection, and hints for where to add features and how to run tests.
8197

82-
Under 100ms for most repos. Under 7 seconds for 20,000+ file repos.
98+
## Set up your AI tools
8399

84-
## Language support
100+
### Claude Code
85101

86-
| Language | Parser | Extracts |
87-
|----------|--------|----------|
88-
| Go | stdlib AST | imports, exports with signatures, struct fields, interface methods |
89-
| TypeScript/JS | tree-sitter | imports (ESM, CJS, dynamic), classes, interfaces, type aliases |
90-
| Python | tree-sitter | imports, classes with methods, type hints, decorators |
91-
| Rust | tree-sitter | use/mod/crate, pub items with generics, trait methods |
92-
| Java | tree-sitter | imports, public classes, method signatures with types |
93-
| C# | tree-sitter | using directives, public types, method signatures |
94-
| Ruby | tree-sitter | require, classes, modules, methods |
95-
| PHP | tree-sitter | namespace use, classes, traits, public methods |
96-
| Kotlin | tree-sitter | imports, classes, objects, functions |
97-
| Swift | tree-sitter | imports, structs, classes, protocols |
98-
| C/C++ | tree-sitter | includes, functions, structs, typedefs |
102+
Add to your project's `CLAUDE.md`:
99103

100-
Generic fallback handles any other language (line count + language detection).
101-
102-
## MCP server
103-
104-
```bash
105-
stacklit serve
104+
```
105+
Read stacklit.json before exploring files. Use modules to locate code, hints for conventions.
106106
```
107107

108-
Seven tools: `get_overview`, `get_module`, `find_module`, `list_modules`, `get_dependencies`, `get_hot_files`, `get_hints`.
108+
### Claude Desktop / Cursor (MCP)
109109

110-
Add to Claude Desktop, Claude Code, or Cursor:
110+
Add to your MCP config:
111111

112112
```json
113113
{
@@ -120,41 +120,30 @@ Add to Claude Desktop, Claude Code, or Cursor:
120120
}
121121
```
122122

123-
For Claude Code without MCP, add to `CLAUDE.md`:
123+
This starts the MCP server with 7 tools: `get_overview`, `get_module`, `find_module`, `list_modules`, `get_dependencies`, `get_hot_files`, `get_hints`.
124124

125-
```
126-
Read stacklit.json before exploring files. Use modules to locate code, hints for conventions.
127-
```
125+
### Any other agent
128126

129-
## Install
127+
`stacklit.json` is a plain JSON file. Any tool that reads files can use it.
128+
129+
## Keep it updated
130130

131131
```bash
132-
npx stacklit init # npm (recommended)
133-
go install github.com/glincker/stacklit/cmd/stacklit@latest # go
132+
stacklit init --hook
134133
```
135134

136-
Binary releases for macOS, Linux, and Windows at [GitHub Releases](https://github.com/glincker/stacklit/releases).
137-
138-
## CLI
139-
140-
```
141-
stacklit init # scan, generate, open HTML
142-
stacklit init --hook # also install git post-commit hook
143-
stacklit init --multi repos.txt # polyrepo: scan multiple repos
144-
stacklit generate # regenerate from current source
145-
stacklit view # regenerate HTML, open in browser
146-
stacklit diff # check if index is stale (Merkle hash)
147-
stacklit serve # start MCP server
148-
```
135+
Installs a git hook that regenerates the index on every commit. Uses Merkle hashing to skip regeneration when only docs or configs changed.
149136

150-
## Git integration
137+
Other ways to keep it fresh:
151138

152139
```bash
153-
stacklit init --hook # auto-regenerate on commit
140+
stacklit generate # manual regeneration
141+
stacklit generate --quiet # silent (for scripts/CI)
142+
stacklit diff # check if the index is stale
154143
```
155144

156145
<details>
157-
<summary>GitHub Action</summary>
146+
<summary>GitHub Action for auto-updates</summary>
158147

159148
```yaml
160149
name: Update stacklit index
@@ -181,6 +170,47 @@ jobs:
181170
182171
</details>
183172
173+
## Visual map
174+
175+
![Stacklit visual map](stacklit-og.png)
176+
177+
`stacklit view` opens the interactive HTML. Four views:
178+
179+
- **Graph** -- Force-directed dependency map. Click a node to see exports, types, files.
180+
- **Tree** -- Collapsible directory hierarchy with file and line counts.
181+
- **Table** -- Sortable module table with search filter.
182+
- **Flow** -- Top-down dependency flow from entrypoints to leaves.
183+
184+
## 11 languages via tree-sitter
185+
186+
| Language | Extracts |
187+
|----------|----------|
188+
| Go | imports, exports with signatures, struct fields, interface methods |
189+
| TypeScript/JS | imports (ESM, CJS, dynamic), classes, interfaces, type aliases |
190+
| Python | imports, classes with methods, type hints, decorators |
191+
| Rust | use/mod/crate, pub items with generics, trait methods |
192+
| Java | imports, public classes, method signatures with types |
193+
| C# | using directives, public types, method signatures |
194+
| Ruby | require, classes, modules, methods |
195+
| PHP | namespace use, classes, traits, public methods |
196+
| Kotlin | imports, classes, objects, functions |
197+
| Swift | imports, structs, classes, protocols |
198+
| C/C++ | includes, functions, structs, typedefs |
199+
200+
Any other language gets basic support (line count + language detection).
201+
202+
## All CLI commands
203+
204+
```
205+
stacklit init # scan, generate, open HTML
206+
stacklit init --hook # also install git post-commit hook
207+
stacklit init --multi repos.txt # polyrepo: scan multiple repos
208+
stacklit generate # regenerate from current source
209+
stacklit view # regenerate HTML, open in browser
210+
stacklit diff # check if index is stale
211+
stacklit serve # start MCP server
212+
```
213+
184214
<details>
185215
<summary>Configuration (stacklit.toml)</summary>
186216
@@ -208,7 +238,6 @@ html = "stacklit.html"
208238
| Monorepo aware | Yes | No | No | No |
209239
| Languages | 11 (tree-sitter) | N/A | Many | 66 |
210240
| Runtime needed | No | No | Yes (Python) | Yes (C server) |
211-
| Single binary | Yes (Go) | No (Node) | No (Python) | Yes (C) |
212241

213242
## Monorepo support
214243

0 commit comments

Comments
 (0)