---
name: repo-map
description: "Generate a token-budgeted, relevance-ranked repository structure map using ripgrep/find and git history — gives the model project awareness without reading every file. Inspired by Aider's RepoMap."
trigger:
  - Starting work on an unfamiliar codebase
  - User asks to understand project structure
  - Need to locate files without reading the full tree
  - Before making changes that span multiple directories
metadata:
  hermes:
    requires_toolsets: [terminal, file]
---

# Repo Map — Repository Structure Awareness

## When to Use

Generate a compact, ranked repo map before working on a large codebase. The map gives the model awareness of file locations, types, sizes, and recent changes in ~500-750 tokens — far less than listing or reading the directory tree.

## How to Use

```bash
# Full repo map (default: 1024 token budget, depth 6)
python3 ~/.hermes/scripts/repo-map.py /path/to/repo

# Higher budget for large repos
python3 ~/.hermes/scripts/repo-map.py ~/Unspooled --budget 2048

# Shallow depth for overview only
python3 ~/.hermes/scripts/repo-map.py ~/Unspooled --depth 2

# JSON output for programmatic use
python3 ~/.hermes/scripts/repo-map.py ~/Unspooled --json
```

## What It Shows

| Column | Meaning |
|--------|---------|
| Type | File category (source, build, config, test, docs, schema) |
| Lang | Detected language |
| File | Relative path (truncated to 60 chars) |
| Lines | Line count |
| 🔄 | Modified in last 7 days (git activity marker) |

## Ranking Logic

Files are ranked by: **file type priority** (source=10, schema=9, build=8, config=7, test=6, docs=4, other=2) + **recent git changes** (+15) + **medium file size bonus** (+5 for <500 lines) + **tiny file penalty** (-3 for <50 lines).

## Pitfalls

- Requires `find` and `git` — available on Linux/macOS by default.
- The map is a **snapshot** — re-run after significant file changes.
- Budget of 1024 tokens covers ~85 files in the formatted table.
- Does NOT replace reading individual files — it tells you WHAT to read.
- Large JSON files (package-lock, database dumps) and binary files are automatically excluded.
- **Large repos (>2000 files):** Use `--depth 4` to limit scope. The script may time out at 10s on repos like Hermes itself (>3,600 files). 
- **Line counts are estimated** (by file extension) — not exact. This is sufficient for ranking but don't use for precise metrics.
- **Kotlin/Android source**: Files at depth 9+ in the project tree may be excluded at default depth 10. Use `--depth 12` for Android projects with deep package hierarchies.
- See `references/benchmark-results.md` for generation speed and accuracy data.