Overview
xtage is a code intelligence layer. It reads your repository and produces a set of structured Markdown files — stored outside the repo under ~/xtage/{repo}/ — that give Claude a token-efficient way to navigate large codebases without loading raw source into context.
Claude reads the index to understand structure, then loads specific chunks only when it needs to work with a particular file.
Install
npm install -g xtageIndex a repo
Run from any directory:
xtage index .xtage writes output to ~/xtage/{repo-name}/. Re-run after significant changes to keep the index fresh.
Index a specific path or repo name:
xtage index /path/to/repo --name my-projectCODEINDEX.md
The primary navigation file. Maps every source file to a short description, its module/layer, and its key exports. Claude reads this first to understand the repo structure without opening any file.
## src/auth/middleware.ts
Layer: middleware | Module: auth
Exports: authMiddleware, requireAdmin
Purpose: Validates JWT tokens and attaches user to request context.REPO.md
A high-level repo narrative — tech stack, architecture overview, entry points, deployment model. Written in plain prose for fast orientation.
PROJECTINSIGHTS.md
Cross-cutting patterns and non-obvious conventions — naming rules, invariants, gotchas, historical decisions. The stuff that isn't in the code itself.
Per-file chunks
Long files are split into chunks stored at ~/xtage/{repo}/chunks/{file-path}.md. Each chunk covers a contiguous range of lines with full context headers. Claude loads chunks on demand instead of reading raw source.