A deterministic code indexing and retrieval system for AI-assisted development.
In Greek mythology, Hermes was the messenger of the gods, known for speed, travel, and delivering information between distant places, Most importantly he was the guide of travelers, the messenger of the gods, and the navigator between worlds. Hermes follows the same philosophy for codebases. It does not attempt to replace understanding. Instead, it guides developers and AI agents through large repositories, helping them navigate directly to the symbols, files, and implementations they need. The repository already contains the answer.
Hermes builds a rich, queryable symbol index of your entire codebase so LLMs can find the right code—fast. Instead of exploring millions of tokens, ask Hermes and jump directly to what matters.
- 🛠️ Installation
- ✨ Key Benefits
- 📖 What is Hermes?
- ⚙️ How It Works
- 🚀 Why Hermes Matters
- 📊 Benchmarks
- 🔎 First Lookup Accuracy
- 📦 When To Use Hermes
- 🔄 Index Once. Query Many.
- 🏗 Architecture
- 🧭 Design Principles
- ⚡ Quick Start
- 🛣 Roadmap
- 🤝 Contributing
- 📄 License
Hermes requires:
- Go 1.24+
- Universal Ctags
sudo apt install universal-ctagssudo pacman -S universal-ctagsbrew install universal-ctagsVerify installation:
ctags --versionExpected output should contain:
Universal Ctags
Install the latest release:
curl -fsSL https://raw.githubusercontent.com/Aeres-u99/hermes/main/install.sh | bashIf ~/.local/bin is not on your PATH, the installer will tell you how to add it.
Verify the installation:
hermes --helphermes --helpDownload the appropriate binary from the GitHub Releases page.
Rename it to hermes, make it executable, and place it somewhere on your PATH:
chmod +x hermes-linux-amd64
mv hermes-linux-amd64 hermes
sudo mv hermes /usr/local/bin/Verify:
hermes --helpRun the installer again or Download manually and install:
curl -fsSL https://raw.githubusercontent.com/Aeres-u99/hermes/main/install.sh | bashgit clone https://github.com/Aeres-u99/hermes.git
cd hermes
makeThis is pending, but we do plan to add tests. Sadly this wasn't made using TDD
make testHermes uses CGo (via Tree-sitter), so cross-compilation requires a C cross-compiler for the target architecture — GOARCH alone is not enough.
Install the cross-compiler:
sudo apt install gcc-aarch64-linux-gnusudo pacman -S aarch64-linux-gnu-gccBuild:
make build-linux-arm64Output: dist/hermes-linux-arm64
Transfer the binary to your ARM machine and install:
scp dist/hermes-linux-arm64 user@arm-host:~
ssh user@arm-host 'sudo install ~/hermes-linux-arm64 /usr/local/bin/hermes'make build-linux-amd64Output: dist/hermes-linux-amd64
Darwin cross-compilation from Linux requires the macOS SDK and is not supported here. Run these on the Mac itself.
make build-darwin-arm64Output: dist/hermes-darwin-arm64
make build-darwin-amd64Output: dist/hermes-darwin-amd64
make build-allProduces both dist/hermes-linux-amd64 and dist/hermes-linux-arm64.
sudo install hermes /usr/local/bin/hermesVerify installation:
hermes --help| 🎯 Direct Navigation | ⚡ High Efficiency | 💰 Lower Cost | 🔍 Works at Scale |
|---|---|---|---|
| Jump directly to implementations without exploring the repository tree. | Reduce repository exploration through targeted symbol retrieval. | Fewer searches, fewer tool calls, lower latency. | Designed for medium and large repositories. |
Hermes is a repository indexing and retrieval system that produces a structured symbol index (hermes.json) of your codebase.
You can then query this index using simple tools such as:
- grep
- jq
- ripgrep
- Claude Code
- Aider
- Custom agents
Instead of feeding your entire repository to an LLM, Hermes retrieves only the relevant functions, types, files, and locations.
Repository
│
▼
Hermes Index
│
▼
grep / jq / rg
│
▼
Relevant Symbols
│
▼
LLM
Hermes parses the repository using Tree-sitter and extracts:
- Functions
- Methods
- Structs
- Interfaces
- Constants
- Variables
- Imports
- File Locations
hermes -input .Output:
hermes.json
Search for symbols using standard UNIX tools.
grep -C3 "ConfigureProvider" hermes.jsonor
jq '.idx["ConfigureProvider"]' hermes.jsonOpen the exact files and locations returned by Hermes.
No blind repository exploration required.
Hermes supports a .hermesignore file to exclude files and directories that provide little or no value for code navigation.
Ignoring generated code, vendored dependencies, documentation, test fixtures, repository metadata, and build artifacts can significantly reduce index size, indexing time, and query noise.
A well-tuned .hermesignore helps Hermes focus on implementation code rather than auxiliary repository content.
# Repository metadata
.git/**
.github/**
# Dependencies
vendor/
node_modules/
# Documentation
docs/
*.md
# Generated files
**/zz_generated.*
**/*_generated.go
# Test fixtures
**/testdata/
**/*_test.go
# Build artifacts
dist/
build/
tmp/
# IDE files
.idea/
.vscode/- ⚡ Faster indexing
- 📉 Smaller index size
- 🎯 Better retrieval precision
- 💰 Lower token consumption
- 🔍 Reduced search noise
Hermes is designed around the principle that not all repository content is equally valuable for navigation. A carefully curated .hermesignore allows the index to focus on the code that matters most.
Tip: For large repositories such as Kubernetes, Loki, or Terraform, excluding
.git/**, vendored dependencies, generated files, and documentation can dramatically reduce index size while preserving the vast majority of implementation-relevant symbols.
Modern LLM workflows spend the majority of their time and tokens exploring repositories.
Typical workflow:
Search
↓
Open File
↓
Wrong File
↓
Search Again
↓
Open More Files
↓
Find Implementation
Hermes transforms that into:
Lookup Symbol
↓
Open Correct File
↓
Done
Benefits:
- Fewer file reads
- Lower token usage
- Fewer tool calls
- Faster navigation
- Lower latency
- Better agent performance
hermes -input .This generates:
hermes.json
which can then be queried using:
jq -r '.idx | keys[]' hermes.jsonor
jq -r '.idx["main.main"]' hermes.jsonHermes has been benchmarked against three real-world repositories of different scales.
| Repository | Files | LOC | Runtime (s) | Full Map Tokens | Query Tokens | Retrieval Reduction |
|---|---|---|---|---|---|---|
| Kubernetes | 30,536 | 5.0M | 66.2 | 14.7M | 2,059 | 99.986% |
| Loki | 17,160 | 510k | 11.6 | 8.4M | 880 | 99.990% |
| Terraform | 5,411 | 667k | 13.8 | 2.0M | 5,340 | 99.732% |
| Repository | Exploration Collapse | Cost Reduction |
|---|---|---|
| Kubernetes | 60.0% | 49.6% |
| Loki | 50.0% | 50.2% |
| Terraform | 62.5% | 7.2% |
Hermes is a retrieval system, not a context-stuffing system.
| Repository | Full Map Tokens | Query Tokens |
|---|---|---|
| Kubernetes | 14,718,000 | 2,059 |
| Loki | 8,396,000 | 880 |
| Terraform | 1,990,000 | 5,340 |
Hermes consistently reduces retrieval payloads by over 99.7%.
The entire repository is never sent to the model.
Only the relevant symbols are retrieved.
| Repository | First Lookup Correct |
|---|---|
| Kubernetes | ✅ Yes |
| Loki | ✅ Yes |
| Terraform | ❌ Required Refinement |
Hermes performs best when queried using specific symbols.
Broad interfaces and common method names may require one or more refinement steps.
Hermes is optimized for medium and large repositories.
| Repository Size | Expected Benefit | Recommendation |
|---|---|---|
| < 100 files | Low | Generally not recommended |
| 100 – 1,000 files | Medium | Situational benefit |
| 1,000 – 10,000 files | High | Strong benefit |
| 10,000+ files | Very High | Primary target |
Smaller repositories may not see enough benefit to offset indexing overhead.
Index generation is a one-time operation.
The resulting index can be reused across:
- Feature development
- Bug investigation
- Architecture discovery
- Code reviews
- AI-assisted programming
- Documentation generation
Repository
│
▼
Generate Index
│
▼
hermes.json
│
├── Query #1
├── Query #2
├── Query #3
├── Query #4
└── Query #N
The generation cost is paid once. Or, if post Query #1 the syntax or structure has changed significantly, regenerate the hermes.json to ensure that the map is not stale.
The retrieval benefit compounds over time.
Repository
│
▼
Tree-sitter Parser
│
▼
Hermes Index
│
├── Functions
├── Methods
├── Structs
├── Interfaces
├── Variables
├── Constants
└── Imports
│
▼
grep / jq / rg
│
▼
LLM / Agent
Never send the entire repository to the model.
Retrieve only the relevant implementation details.
Same repository → same index.
No embeddings.
No probabilistic ranking.
Indexes are human-readable and versionable.
You can inspect, diff, and audit every result.
Works with standard UNIX tooling:
- grep
- jq
- rg
- awk
- sed
Built on Tree-sitter.
Designed to understand source structure rather than plain text.
Hermes Help
❯ hermes --help
hermes - The Code Map you will Ever need!
For custom CTAGS path use Environment Variable HERMES_CTAGS for custom path
-input string
Code to Parse (default "code.py")
-output string
Code to Parse (default "hermes.json")
Have Fun
Generate an index:
hermes -input .Search for a symbol:
grep -C3 "MyFunction" hermes.jsonRetrieve with jq:
jq '.idx["MyFunction"]' hermes.jsonOpen the returned file and line.
Done.
- TODO
- Incremental indexing
- Multi-language support
- Cross-reference graph
Contributions, bug reports, and feature requests are welcome.
Please open an issue or submit a pull request.
MIT