https://github.com/nguyenyou/kodex
Compiler-precise Scala code intelligence, built in Rust. Best for: codebase Q&A, knowledge base generation, onboarding to unfamiliar code, production spec sync.
https://github.com/nguyenyou/kodex
call-graph cli code-intelligence code-navigation coding-agent developer-tools rust scala semanticdb static-analysis
Last synced: 4 days ago
JSON representation
Compiler-precise Scala code intelligence, built in Rust. Best for: codebase Q&A, knowledge base generation, onboarding to unfamiliar code, production spec sync.
- Host: GitHub
- URL: https://github.com/nguyenyou/kodex
- Owner: nguyenyou
- License: mit
- Created: 2026-03-30T03:11:24.000Z (11 days ago)
- Default Branch: main
- Last Pushed: 2026-03-31T11:02:48.000Z (10 days ago)
- Last Synced: 2026-04-03T04:57:36.088Z (7 days ago)
- Topics: call-graph, cli, code-intelligence, code-navigation, coding-agent, developer-tools, rust, scala, semanticdb, static-analysis
- Language: Rust
- Homepage: https://nguyenyou.github.io/kodex/
- Size: 1.82 MB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# kodex
**K**nowledge + C**ode** + Inde**x** = **Kodex.** Compiler-precise Scala code intelligence for coding agents.
**Best for:** codebase Q&A, knowledge base generation, onboarding to unfamiliar code, production spec sync.
> Our mascot is a raven, inspired by Odin's ravens Huginn and Muninn â who flew across the world each day and returned to whisper everything they had seen. kodex does the same for codebases.
## Why I Built This
I work across many domains and products at work â codebases I don't have deep knowledge about. The usual workflow: figure out how to set something up, realize I don't know how, go find the engineer who owns that domain and ask them. That's friction.
I built kodex so that Claude Code can answer those questions instead. *How do I create X? How does Y work? What are the requirements for Z to be properly set up?* It traces through the compiled codebase and gives me a precise answer.
This tool is built for **reading code, not writing code**.
## Quick Start
**1. ðŠķ Summon it** â install the plugin (one-time):
```
/plugin marketplace add nguyenyou/kodex
/plugin install kodex@kodex-marketplace
```
**2. ð Let it fly** â ask away:
```
use kodex to explore how authentication works in this codebase
```
> The coding agent knows how to compile SemanticDB for Mill, sbt, and scala-cli projects â just ask and it will handle the build for you.
## Recommended Workflows
### Knowledge base generator (automated)
A server runs daily/weekly to clone the production codebase, compile SemanticDB, and let an AI agent use kodex to generate product specs. Specs stay in sync with the actual code â generated from code, not the other way around.
### Read-only explorer (what I use)
Keep two clones of the production codebase:
- **Read-only clone** â compiled with SemanticDB, used with kodex for understanding
- **Working clone** â where you write code
Your kodex index stays stable and doesn't get invalidated by in-progress changes.
## scalex vs kodex
```
scalex: .scala âââķ Parser âââķ AST âââķ Index & Query
kodex: .scala âââķ Compiler âââķ SemanticDB âââķ Index & Query
(expensive) (precise)
```
| | **scalex** | **kodex** |
|---|---|---|
| **Setup cost** | None â instant on any Scala codebase | Requires a full compile |
| **Accuracy** | Best-effort (unresolved implicits, overloads) | Compiler-precise â every symbol resolved |
| **Speed to first query** | Seconds | Minutes (compile time) |
| **Best for** | Quick exploration, reading unfamiliar code | Deep understanding, production codebases |
I use both. **scalex** is my default for open source projects and libraries â no setup, instant answers. Opus 4.6 is good enough at reasoning that AST + source code alone is more than enough to explain how a project works. **kodex** is for production codebases where I already compile the code for work, so the cost is paid and I want compiler-precise accuracy.
## Credits
- **[Scala](https://github.com/scala/scala3) & [Scalameta](https://github.com/scalameta/scalameta)** â for building [SemanticDB](https://scalameta.org/docs/semanticdb/guide.html), the compiler output format that makes this tool possible.
- **[Metals](https://github.com/scalameta/metals)** â for showing how to compile SemanticDB across sbt and scala-cli projects.
- Built with **[Claude Code](https://claude.com/claude-code)** (Opus 4.6).
## License
[MIT](LICENSE)