compactr

name	compactr
description	Repository context index for semantic file discovery. Use this before broad grep, glob, find, or code searches when deciding which files to read. Query the Compactr map first, then read the smallest useful subset of returned files unless the results are empty or insufficient.

Compactr

Compactr maintains .compactr/project-map.json, a local repository map containing paths, languages, imports, exports, summaries, mtimes, and hashes. Use it as a low-token relevance oracle before broad file searches.

When to use

Use Compactr before semantic repository discovery:

• "Where is auth handled?"
• "Find the files for billing"
• "What should I read to fix this route?"
• Any task where you would otherwise start with grep, rg, glob, find, or a repo-wide scan.

If you already know the exact path, filename, or symbol, use the normal search/read tool directly. Compactr is optimized for reducing follow-up file reads, not for replacing a raw path list.

Do not treat Compactr as ground truth. It returns hints. If the returned files do not explain the behavior, continue with normal search tools.

Commands

Run the script from this skill directory:

node .\skills\compactr\compactr.mjs query "auth middleware"
node .\skills\compactr\compactr.mjs query "auth middleware" --verbose
node .\skills\compactr\compactr.mjs build
node .\skills\compactr\compactr.mjs build --force
node .\skills\compactr\compactr.mjs status
node .\skills\compactr\compactr.mjs install-instructions

On macOS/Linux, use / path separators.

Workflow

1. Run query "<task terms>" before broad search.
2. If the task is planning or file discovery, use read paths and reasons as candidate answers; do not read files unless a returned path is ambiguous or contradictory.
3. If implementation requires code details, read only the strongest 1-3 matches first.
4. Prefer results with strong reasons like symbol, import, or path matches.
5. Use alsoExplore as cheap directory/neighborhood hints for narrow follow-up search when the first files do not explain the task.
6. If read is empty, the output has a low-confidence note, or the returned files do not explain the task, immediately continue with normal search tools.
7. If the map is missing or stale, query refreshes it opportunistically. Use build --force only when the map looks wrong.
8. Use status to inspect map age, indexed files, skipped files, last build duration, and lock state.

Output

query returns compact ranked starting points by default:

{"read":[{"path":"src/auth/session.ts","why":"symbol:createSession; import:jwt","summary":"Session helpers for auth tokens."}],"alsoExplore":[{"path":"src/auth/","why":"near matched files"}],"note":"Starting points, not exhaustive. For planning, use paths/reasons as candidate answers; do not read files unless a path is ambiguous."}

When Compactr has no useful match, it returns an explicit fallback note:

{"read":[],"note":"No Compactr matches; use grep or normal search."}

Use --verbose when you need scores, full imports/exports, hashes, mtimes, or map metadata.

Optional repo instruction

If the agent does not reliably use Compactr first, run:

node .\skills\compactr\compactr.mjs install-instructions

This appends a short .github/copilot-instructions.md note telling Copilot to query Compactr before broad repository search.