# Project Index

> Token-efficient codebase navigation via a persistent code index. Use at the START of any work session on a code project (repository, codebase, multi-file project) and for any structural question about code — "where is X defined", "who uses/imports Y", "what breaks if I change Z", "what is the structure of this project". Builds .claude/index/ once, updates incrementally, then answers structural questions with cheap queries instead of grep + reading whole files. Do NOT use for single-file scripts or non-code folders.

- Skill: `iskendernarynbaev-lab/project-index` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add iskendernarynbaev-lab/project-index`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iskendernarynbaev-lab/project-index/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iskendernarynbaev-lab (https://skillmd.com/u/iskendernarynbaev-lab)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/iskendernarynbaev-lab/project-index

---


# project-index

Persistent, incrementally-updated code index. Replaces repeated re-analysis
(grep + reading whole files) with cheap targeted queries. Typical savings:
90–98% of tokens on structural questions.

Script: `scripts/project_index.py` (run with `python3`, from repo root or with `--root DIR`).

Dependencies (auto-degrades to regex mode if missing):
`pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-rust tree-sitter-java --break-system-packages -q`

Languages with full AST parsing: Python, JS/JSX, TS/TSX, Go, Rust, Java.
Others (Ruby, PHP, C#, Kotlin, Swift): regex fallback, symbols only.

## Workflow — follow this order

**1. Session start (ALWAYS, before any grep/find/ls exploration):**

```
python3 scripts/project_index.py update --root <repo>   # builds or incrementally refreshes
python3 scripts/project_index.py map --root <repo>      # ~1-2K token project overview
```

`update` is cheap: unchanged files are skipped by content hash. The `map`
output gives directories, entry points, and most-imported (core) modules —
usually enough to orient without reading any file.

**2. Structural questions — query the index, do NOT grep:**

| Question | Command |
|---|---|
| Where is symbol X defined? | `where X` (exact) / `search X` (substring) |
| What's in file F? (API surface) | `file F` — symbols with lines + imports |
| What does F import? | `imports F` |
| Who imports F? | `importers F` |
| What breaks if I change F? | `impact F` — transitive reverse deps by depth |
| Is index fresh? | `stats` |

File arguments accept suffixes: `importers utils.js` works if unambiguous.

**3. Read code only after the index has narrowed the target.** Use `file F`
to get the line number of the symbol, then Read that specific range —
not the whole file.

**4. After editing files:** run `update` again (fast) so later queries stay
correct. If `stats` reports stale files, run `update` before trusting queries.

## When grep is still the right tool

The index knows *structure* (definitions, imports), not *content*. Use grep
for: string literals, comments, config values, usage sites *inside* function
bodies. Rule of thumb: "where is it defined / who depends on it" → index;
"where does this exact text appear" → grep.

## Artifacts

Index lives in `<repo>/.claude/index/` — `index.json` (machine, queried by
script) and `MAP.md` (human/agent readable). Add `.claude/index/` to
`.gitignore` or commit it — either works; `update` self-heals stale state.
`MAP.md` records the commit hash it was built at.