Read and understand a codebase with minimal token use. Use this skill for Claude Code or Codex whenever you need to explore a repo, understand project structure, explain architecture, locate symbols, navigate modules, or answer questions that need broad codebase context before reading files. Triggers include: "read my project", "understand this codebase", "explore this repo", "what does this project do", "help me with this codebase", "navigate this code", "explain this architecture", "find this function", "tim hieu project", "doc code", "hieu codebase", and similar requests.
Use ai-lens before reading files one by one. The default workflow is:
scan: build or refresh the local project index.query: ask the index for the files, symbols, and ranges that matter.read: open only the relevant file chunks after the index narrows scope.agents/openai.yaml adds UI metadata only.Run from the project root:
python scripts/scan.py .
Use --force for a full rebuild and --full-dump if you also want .ai-lens.json.
What scan does:
.gitignore and common generated directories..ai-lens/manifest.json plus per-file cache records.Common queries:
python scripts/query.py --index . --type architecture
python scripts/query.py --index . --symbol startServer
python scripts/query.py --index . --related authentication
python scripts/query.py --index . --dependents src/models/user.ts
python scripts/query.py --index . --pattern "routes/*"
Use --json when another tool or automation needs structured output.
After query, open only the relevant lines from the highest-ranked files. Prefer:
Avoid reading entire large files unless the narrowed ranges are still insufficient.
scan after large code changes or when query reports a stale index.--type architecture: use for first-pass repo understanding.--symbol NAME: use when a function, class, method, or type is named.--related TEXT: use for bugs, features, or error strings.--dependents PATH: use to see impact and callers/importers.--pattern GLOB: use when the module area is known already.