Lightweight AST-based codebase indexer for AI coding assistants. Generates a
metaend.eth.xyz
relationships.json that Claude Code / Cursor / etc. can reference instead of exploring the entire codebase.
paragraph.com/@metaend
ai
llm
eco
ast
golang
1# Codebase Indexer
2
3Lightweight AST-based codebase indexer for AI coding assistants. Generates a `relationships.json` that Claude Code / Cursor / etc. can reference instead of exploring the entire codebase.
4
5## Supported Languages
6
7- JavaScript / TypeScript (.js, .jsx, .ts, .tsx)
8- Astro (.astro) — parses frontmatter imports, treats component as default export
9- Go (.go)
10- Python (.py)
11- Clojure / ClojureScript (.cljs, .clj, .cljc) — detected but not yet parsed (no tree-sitter grammar available)
12
13## Install
14
15```bash
16cd /path/to/codebase-indexer
17go build -o ~/go/bin/codebase-indexer .
18```
19
20Make sure `~/go/bin` is in your `PATH`.
21
22## Usage
23
24```bash
25codebase-indexer -root . -out .context/relationships.json
26```
27
28### Flags
29
30- `-root` — project root directory (default: `.`)
31- `-out` — output JSON file (default: `.context/relationships.json`)
32
33## Integration with AI Assistants
34
35Copy the snippet from `CLAUDE.md.example` into your project's `CLAUDE.md` (or `AGENTS.md`).
36
37## Auto-index on Commit (Optional)
38
39```bash
40cp post-commit .git/hooks/
41chmod +x .git/hooks/post-commit
42```
43
44## Watch Mode (Optional)
45
46Requires `fswatch` (`brew install fswatch` / `apt install fswatch`).
47
48```bash
49./watch-index.sh
50```
51
52## Output Format
53
54```json
55{
56 "files": {
57 "src/utils.py": {
58 "language": "python",
59 "imports": ["os", "pathlib"],
60 "exports": ["load_config", "Config"],
61 "defines": [
62 {"name": "Config", "type": "class", "line": 4},
63 {"name": "load_config", "type": "function", "line": 8}
64 ]
65 }
66 },
67 "symbols": {
68 "Config": {"file": "src/utils.py", "line": 4, "type": "class"}
69 },
70 "dependencyGraph": {
71 "src/utils.py": ["os", "pathlib"]
72 }
73}
74```
75
76## .gitignore
77
78Add if you don't want to track the index:
79
80```
81.context/
82```
83
84Or keep it tracked so it's available immediately on clone.
85
86## Extending
87
88To add more languages, add a tree-sitter grammar import and a `parseXXX()` function. Tree-sitter has grammars for 100+ languages.
89
90```go
91import "github.com/smacker/go-tree-sitter/rust"
92
93// In parseFile() switch:
94case "rust":
95 treeSitterLang = rust.GetLanguage()
96
97// Add extension mapping
98".rs": "rust",
99
100// Add parser function
101func parseRust(root *sitter.Node, content []byte) FileInfo {
102 // ...
103}
104```