{"id":49016282,"url":"https://github.com/dotcommander/repomap","last_synced_at":"2026-04-27T23:00:30.203Z","repository":{"id":351838997,"uuid":"1209742922","full_name":"dotcommander/repomap","owner":"dotcommander","description":"Token-budgeted repository maps for LLM context windows — scan, parse, rank, budget, format. Go library + CLI.","archived":false,"fork":false,"pushed_at":"2026-04-19T01:40:21.000Z","size":318,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T02:44:27.940Z","etag":null,"topics":["cli","code-navigation","codebase","context-window","developer-tools","go","golang","llm","repository-map","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotcommander.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T18:29:47.000Z","updated_at":"2026-04-19T01:40:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dotcommander/repomap","commit_stats":null,"previous_names":["dotcommander/repomap"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/dotcommander/repomap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Frepomap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Frepomap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Frepomap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Frepomap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotcommander","download_url":"https://codeload.github.com/dotcommander/repomap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Frepomap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32358509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"ssl_error","status_checked_at":"2026-04-27T20:07:00.910Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","code-navigation","codebase","context-window","developer-tools","go","golang","llm","repository-map","tree-sitter"],"created_at":"2026-04-19T02:16:39.007Z","updated_at":"2026-04-27T23:00:30.198Z","avatar_url":"https://github.com/dotcommander.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# repomap\n\nA repository becomes a map.\n\n```\n$ repomap .\n## Repository Map (41 files, 119 symbols)\n\n### Dependencies\nrepomap/cmd/repomap → repomap/internal/cli\nrepomap/internal/cli → repomap\n\ncmd/repomap/main.go [entry]\n  func main()\n\nrepomap.go [imported by 1]\n  type Config{MaxTokens int, MaxTokensNoCtx int, ...}\n    // holds options for a Map build\n  type Map\n    // is the top-level orchestrator. Thread-safe.\n  func New(root string, cfg Config) *Map\n    // creates a Map for root with the given config\n  func (m *Map) Build(ctx context.Context) error\n    // scans, parses, ranks, and budgets the repository\n  func (m *Map) String() string\n  func (m *Map) StringCompact() string\n  func (m *Map) StringVerbose() string\n  func (m *Map) StringDetail() string\n  func (m *Map) StringLines() string\n  func (m *Map) StringXML() string\n```\n\nThat is the point.\n\n## The Problem\n\nLLMs work best when they can see a whole codebase at once. Most codebases are too large. `find`, `tree`, and `ls -R` hand the model noise. A full `cat **/*.go` blows the context window in one shot.\n\nYou want the skeleton. Every package. Every exported symbol. Nothing else.\n\n## The Shape\n\nrepomap runs a five-stage pipeline on your project root:\n\n```\nscan → parse → rank → budget → format\n```\n\n**Scan** walks `git ls-files` and detects languages.\n**Parse** extracts symbols — `go/ast` for Go, tree-sitter for seven other languages, regex where neither reaches.\n**Rank** scores files: entry points float, leaves sink.\n**Budget** trims to fit a token ceiling you pass in.\n**Format** prints compact Markdown, verbose text, source lines, or structured XML.\n\nThe output fits in a prompt. The prompt fits in the model. The model reads the repository.\n\n## Install\n\n```bash\ngo install github.com/dotcommander/repomap/cmd/repomap@latest\n```\n\nOr clone and build:\n\n```bash\ngit clone https://github.com/dotcommander/repomap\ncd repomap\ngo build -o repomap ./cmd/repomap\n```\n\n## Use\n\n```bash\nrepomap                             # current directory, 2048 tokens, enriched default\nrepomap ./src                       # target a subtree\nrepomap -t 4096                     # wider budget\nrepomap -f compact                  # lean orientation: file paths + symbol names only\nrepomap -f verbose                  # every symbol, no summarization\nrepomap -f detail                   # signatures and struct fields (same as default, no budget cap)\nrepomap -f lines                    # actual source lines, not summaries\nrepomap -f xml                      # structured output for programmatic consumers\nrepomap --json                      # JSON envelope {schema_version:1, lines:[...]}\nrepomap --json --json-legacy        # bare []string JSON (pre-v0.7.0 compat)\n```\n\n### Output formats\n\n| Format | What it shows | Budget enforced |\n|--------|---------------|----------------|\n| *(default)* | Paths, exported symbol names, typed signatures, godoc first sentence, typed struct fields | Yes |\n| `compact` | Paths + exported symbol names only — lean orientation mode | Yes |\n| `verbose` | All symbols, names only, no summarization | No |\n| `detail` | All symbols, signatures, and struct fields | No |\n| `lines` | Actual source lines | No |\n| `xml` | Structured XML for programmatic consumers | No |\n\n**Budget guarantee**: repomap never truncates a file mid-symbol. Files either render fully at their assigned detail level or drop to a lower level or are omitted — token budget is honored exactly. The footer reports how many files were omitted.\n\n## Quickstart\n\n```bash\nrepomap init                        # scaffold .repomap.yaml + post-commit hook\nrepomap init --no-hook              # config only\nrepomap init --force                # overwrite existing\n```\n\n`repomap init` writes `.repomap.yaml` at the project root and installs a\ngit `post-commit` hook that refreshes the cache in the background after\nevery commit, so `repomap` stays instant. Idempotent — re-running without\n`--force` skips existing files.\n\n## Languages\n\nGo, PHP, Python, Rust, TypeScript, JavaScript, Java, C, C++, Ruby, HTML, CSS. Go parses through `go/ast` directly; PHP parses through tree-sitter with full 8.x coverage (signatures, visibility, constructor property promotion, PHPDoc). The rest go through tree-sitter when the grammar is present, ctags when it is not, regex when neither exists. Quality degrades gracefully; the map is never empty because a parser was missing.\n\n## Configuration\n\nCreate `.repomap.yaml` at the project root to filter symbols from the output:\n\n```yaml\nmethod_blocklist:\n  - \"Test*\"           # glob: drop anything starting with \"Test\"\n  - \"*Mock\"           # glob: drop anything ending in \"Mock\"\n  - \"/^pb_/\"          # regex: drop generated protobuf methods\n```\n\nPatterns wrapped in `/.../` are Go regex; others are `path.Match` globs.\nAbsent file = no filtering.\n\n## Library\n\n```go\nimport \"github.com/dotcommander/repomap\"\n\nm := repomap.New(\".\", repomap.Config{MaxTokens: 2048})\nif err := m.Build(context.Background()); err != nil {\n    return err\n}\nfmt.Print(m.String())\n```\n\nEvery format has a method: `String`, `StringCompact`, `StringVerbose`, `StringDetail`, `StringLines`, `StringXML`. Results cache per format; call them as often as you like.\n\n`String()` is the enriched default: full typed signatures, godoc first sentences, and typed struct fields for exported symbols, within the token budget. `StringCompact()` is the lean orientation mode — symbol names only, no signatures or docs.\n\n`m.Stale()` reports whether source files have changed since the last build. Rebuild when it returns true.\n\n## Design\n\nOne package. No internal taxonomy of subpackages. Files named after what they do — `scanner.go`, `ranker.go`, `budget.go`, `render.go`. If a thing has a name, the file has that name. If a thing has a pipeline stage, the file has that stage.\n\nDocs live in `docs/`. Read them in the order they're numbered.\n\n## Acknowledgments\n\nThe repository map concept was pioneered by [aider.chat](https://aider.chat/) — an AI pair programming tool that introduced the idea of distilling a codebase into a compact symbol map that fits in an LLM context window.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotcommander%2Frepomap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotcommander%2Frepomap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotcommander%2Frepomap/lists"}