Your agent greps the whole repo. It doesn't have to.

Prefixer is an agent skill for scoped codebase search.

AI coding agents that grep the whole tree pay for every irrelevant hit in tokens and tool calls. Prefixer gives the agent a small namespace map: short prefixes pointing at the parts of the repo that matter. Searches start scoped, widen on a miss, and land in the right files first.

The whole thing is Markdown and shell scripts; nothing runs as a service. One SKILL.md, five reference playbooks, and a small toolkit for scaffolding, linting, measuring, and evaluating. It works with any agent that reads skills: Devin, Claude Code, Codex, Cursor, Windsurf, and friends.

How it works

• Scope first. On entry to a repo, the agent reads .prefixer/namespaces.md, rows like auth: | src/auth/** | login, tokens, sessions, and searches inside the matching namespace instead of the whole tree.
• Derived, not declared. The scaffold names namespaces from the codebase's own vocabulary, like a dir-name segment no sibling shares or the dominant term in the files a row scopes. No hardcoded wordlist. Every map carries a repo: qualifier, so payments:auth: and checkout-service:auth: stay distinct across codebases, and rows nest for sub-teams (payments:checkout:).
• Map the segment, not the world. No map? The agent builds only the 3-5 namespaces the current task touches. A partial map is a legal, working state.
• Widen one level on a miss. A scoped search that misses widens to the parent scope, then the root. Never a blind second pass.
• Measure the delta. Each scoped search appends a line to .prefixer/metrics.jsonl. check_namespaces.sh lints the map for dead scopes; eval_repo.sh produces the bytes-saved number.
• See it. scripts/visualize.py renders an interactive HTML report: the map painted on your file tree, coverage per namespace, and scoped-vs-root byte bars, in one file with no dependencies.

Measured on public repos, including the skill repos agents install

Corpus mean: 79% across 18 repos, 149 namespaces. Regenerated weekly from eval/repos.txt by CI; full table and method in eval/RESULTS.md.

$ bash scripts/eval_repo.sh ~/repos/superpowers

checked 12 namespaces: 0 failures, 9 warnings

tag                      root_hits  root_bytes   ns_hits    ns_bytes     pct
assets:                         44        5242         0           0     n/a
docs:                          177       34962        66       10682     69%
hooks:                         203       29348         7         470     98%
scripts:                       230       36229        19        2061     94%
skills:                        873      122699       135       23446     80%
tests:                         459       73555       117       11382     84%
agents:                        245       47554         0           0     n/a
plugin:                        679       88756         0           0     n/a
claude:                        178       36192         0           0     n/a
codex:                         196       30093         0           0     n/a
cfg:                             4         572         0           0     n/a
boot:                          313       41787         0           0     n/a

mean pct_saved: 85% across 5 namespaces
(7 namespaces n/a: 0 hits for their own name; probe them with real query patterns)

Scoped grep vs root grep, same query per namespace. bash scripts/eval_repo.sh <repo> on your own repo gets your numbers.

Install

npx skills add Albisourous/prefixer

Or auto-detect your agent: the installer checks for .claude, .devin, and .agents markers and installs there:

git clone https://github.com/Albisourous/prefixer /tmp/prefixer
bash /tmp/prefixer/scripts/install.sh

Or copy SKILL.md, references/, and scripts/ into .agents/skills/prefixer/ (or .devin/skills/prefixer/, ~/.config/devin/skills/ for Devin) in your project. Full instructions in the README.

Good fit if

• You work in a large repo, a monorepo, or many codebases at once.
• Agent searches return walls of hits from the wrong modules.
• You want a persistent orientation map future sessions reuse.
• You index docs or chunks for RAG and want tighter embeddings.
• You care about prompt-cache hits and token cost, and want them measured.

Three prefix positions

The index-time and cache-ordering playbooks ship in references/. DESIGN.md collects the research base: Anthropic Contextual Retrieval, index-time prefix injection (ACL 2026), Prompt Cache, and RadixAttention. Read it.

FAQ