Content
# olt — Odin Language Tools
A [Clippy](https://github.com/rust-lang/rust-clippy)-inspired static analyser for the [Odin programming language](https://odin-lang.org).
Catches memory leaks, double-frees, naming violations, unchecked errors, and more — before the compiler or runtime does.
```
$ olt src/
🔴 src/core/main.odin:42:5: C001 [correctness] Allocation without matching defer free
Fix: Add 'defer delete(buf)' immediately after the allocation
🔴 src/api/handlers.odin:18:9: C201 [correctness] error return of 'os.open' is discarded
1 violation(s) in 2 file(s)
```
---
## Install
### Pre-built binaries
Download from [Releases](https://github.com/RainerXE/odintooling/releases) for your platform, then:
```bash
olt setup # OLS detection → install → MCP registration (3-step wizard)
```
### Build from source
Requires Odin `dev-2026-05` or newer.
```bash
git clone --recurse-submodules https://github.com/RainerXE/odintooling
cd odintooling
./scripts/build.sh # → artifacts/macos-arm64/olt
```
### First-run setup
```bash
olt setup # full system setup — runs the 3-step wizard below
olt init # create olt.toml in a project directory
```
`olt setup` is a 3-step wizard:
**Step 1 — OLS** — detects [OLS](https://github.com/DanielGavin/ols) in `PATH` (both `ols` and `ols_lsp` / Homebrew). Lets you confirm or override the path.
**Step 2 — Install** — copies `olt` to `~/.local/bin/` and creates three symlinks that enable argv[0] dispatch:
- `ols → olt` — point your editor here instead of vanilla OLS
- `olt-lsp → olt` — backward-compat LSP name
- `olt-mcp → olt` — backward-compat MCP name
**Step 3 — MCP** — detects installed AI coding tools and registers `olt-mcp` in each one's config file automatically. Supports:
| Tool | Config file written |
|------|-------------------|
| Claude Code | `claude mcp add` (CLI) |
| Cursor | `~/.cursor/mcp.json` |
| Cline | `…/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
| Codex | `~/.codex/config.toml` |
| OpenCode | `~/.config/opencode/opencode.json` |
| Antigravity | `~/.gemini/antigravity/mcp_config.json` |
| Hermes Agent | `~/.hermes/config.yaml` |
Config paths resolve correctly on macOS, Linux, and Windows. If a tool's config directory isn't at the expected location, the wizard asks for it.
`olt init` checks whether setup has been run and offers to run it first if needed.
---
## Usage
```bash
olt src/ # lint a directory (recursive)
olt file.odin # lint a single file
olt src/ --fix # apply safe auto-fixes in-place
olt src/ --format json # machine-readable output (json or sarif)
olt src/ --rule C001,C201 # run specific rules only
olt src/ --tier correctness # run only correctness-tier rules
olt --explain C001 # detailed rule documentation
olt --list-rules # show all available rules
olt mcp # start MCP server (AI agent interface)
olt lsp # start LSP proxy (editor interface)
```
### Exit codes
| Code | Meaning |
|------|---------|
| `0` | No violations |
| `1` | One or more violations |
| `2` | Usage error or internal failure |
---
## Rules
### Correctness
| Rule | What it catches |
|------|----------------|
| C001 | Heap allocation (`make`/`new`) without `defer delete`/`defer free` |
| C002 | Double-free or use-after-free |
| C009 | Deprecated `core:os/old` import — use `core:os` |
| C010 | `Small_Array` superseded by `[dynamic; N]T` |
| C011 | FFI C resource (`ts_*_new`) without matching `defer ts_*_delete` |
| C101 | `context.allocator` reassigned without defer restore |
| C201 | Error return value discarded (unchecked result) |
| C202 | Switch on enum not exhaustive (requires `--export-symbols`) |
| C203 | `defer` in inner block fires before outer scope uses the handle |
### Style
| Rule | What it catches |
|------|----------------|
| C003 | Procedure names must be `snake_case` |
| C007 | Type/struct/enum names must be `PascalCase` |
| C016 | Local variable names must be `snake_case` (default on) |
| C031 | `panic()` on expected runtime failure — consider error return (INFO) |
| C034 | `for v, _ in collection` — blank index unnecessary (INFO, auto-fix) |
| C037 | Trailing `return` at end of void procedure (INFO, auto-fix) |
### Opt-in domains
Enable in `olt.toml`:
| Domain | Rules | What it enables |
|--------|-------|----------------|
| `stdlib_safety = true` | C029, C033 | `strings.split/clone/join`, `fmt.aprintf`, `os.read_entire_file` without `defer delete`; `strings.builder_make` without `defer strings.builder_destroy` |
| `go_migration = true` | C021–C023, C025 | Go-style `fmt.Println`, `for i,v := range`, `*ptr` deref, `append(s,v)` without `&` |
| `semantic_naming = true` | C012 | Ownership naming hints (`_ptr`, `_owned`, etc.) |
| `dead_code = true` | C014, C015 | Unexported procedures and constants never referenced |
| `ffi = true` | C011 | FFI resource safety (auto-detected if `ffi/` directory exists) |
---
## Configuration — olt.toml
Run `olt init` in your project directory to generate one, or create it manually:
```toml
[domains]
ffi = true # C011: FFI resource safety
odin_2026 = true # C009/C010: deprecated API detection
stdlib_safety = true # C029/C033: stdlib allocation safety
[naming]
c016 = true # local variables must be snake_case
c019 = false # type marker suffixes (opt-in)
c020 = false # minimum name length (opt-in)
c020_min_length = 3
c020_allowed = "i,j,k,x,y,z,n,ok,err,db,id"
[tools]
ols_path = "/usr/local/bin/ols_lsp" # path to OLS (if not in PATH)
```
### Inline suppression
```odin
buf := make([]u8, n) // olt:ignore C001 arena-managed, freed by caller
```
Multiple rules: `// olt:ignore C001,C002`
Legacy alias `// odin-lint:ignore` is also accepted.
---
## Editor integration
`olt lsp` is an LSP proxy: your editor talks to it as the single Odin language server.
It forwards everything to vanilla [OLS](https://github.com/DanielGavin/ols) (completions, hover, go-to-definition) and injects olt diagnostics into the diagnostic stream.
After `olt setup`, an `ols` symlink is created pointing to `olt`. Point your editor at that symlink — no other changes needed.
**VS Code** (`settings.json`):
```json
"odin.languageServer.path": "/path/to/ols"
```
**Helix** (`languages.toml`):
```toml
[[language]]
name = "odin"
language-servers = ["ols"]
[language-server.ols]
command = "/path/to/ols"
```
**Neovim** (lspconfig):
```lua
require('lspconfig').ols.setup { cmd = { '/path/to/ols' } }
```
OLS must be installed separately: [github.com/DanielGavin/ols](https://github.com/DanielGavin/ols).
Homebrew installs it as `ols_lsp` — `olt setup` detects both names automatically.
---
## AI agent integration
`olt mcp` exposes olt as an [MCP](https://modelcontextprotocol.io) server for Claude Code and other AI agents.
`olt setup` registers `olt-mcp` automatically for every detected tool (see [First-run setup](#first-run-setup)).
For manual registration, add to your tool's MCP config file — the binary is `~/.local/bin/olt-mcp` after setup:
```json
{
"mcpServers": {
"olt-mcp": { "command": "/Users/you/.local/bin/olt-mcp", "args": [] }
}
}
```
Codex (`~/.codex/config.toml`):
```toml
[mcp_servers.olt_mcp]
command = "/Users/you/.local/bin/olt-mcp"
enabled = true
```
Hermes Agent (`~/.hermes/config.yaml`):
```yaml
mcp_servers:
olt-mcp:
command: /Users/you/.local/bin/olt-mcp
args: []
```
Available MCP tools:
| Tool | Description |
|------|-------------|
| `lint_file` | Lint a file on disk |
| `lint_snippet` | Lint in-memory source text |
| `lint_fix` | Return proposed fixes as JSON |
| `lint_workspace` | Batch-lint a directory |
| `list_rules` | Return the full rule catalog as JSON |
| `run_odin_check` | Run `odin check` and return compiler diagnostics |
| `get_symbol` | Look up a symbol in the code graph |
| `export_symbols` | Build the code knowledge graph |
| `get_dna_context` | Callers, callees, memory role for a proc |
| `get_impact_radius` | Transitive impact of changing a symbol |
| `get_callers` / `get_callees` | Direct call graph neighbours |
| `search_symbols` | Full-text symbol search |
| `rename_symbol` | Generate rename patches across the project |
### Code knowledge graph
Build a semantic graph of your project for deeper analysis:
```bash
olt src/ --export-symbols
```
By default this writes to `.codegraph/odin_lint_graph.db` and `.codegraph/symbols.json`. Pass a custom path via `--db=<path>` or the MCP `export_symbols` tool.
Add `.codegraph/` to your `.gitignore` to keep generated graph files out of version control:
```
.codegraph/
```
Once exported, this enables:
- C202 switch exhaustiveness checking
- All `get_*` / `search_symbols` MCP tools for AI-assisted refactoring
### CodeGraph integration
[CodeGraph](https://github.com/colbymchenry/codegraph) is a code intelligence MCP server that gives AI agents fast symbol search, call graphs, and impact analysis across 19+ languages. olt can write a CodeGraph-compatible database so Odin projects work with it too.
**First-time setup** (run once per project):
```bash
olt --codegraph-init . # index current directory
olt --codegraph-init src/ # or a specific subdirectory
```
A target directory is required — `olt --codegraph-init` without one will exit with an error. Use `.` to index the current directory. This does a full index and writes `.codegraph/codegraph.db` in the schema CodeGraph expects. It also writes `.codegraph/.gitignore` so the database is not committed. No `codegraph init` needed — olt handles everything.
**Keeping it updated** (run after code changes):
```bash
olt --codegraph-sync . # sync current directory
olt --codegraph-sync src/ # or a specific subdirectory
```
A target directory is required here too. Incremental — only re-indexes changed files. Prints a clear error if `--codegraph-init` has not been run yet.
Once the database is in place, all CodeGraph MCP tools work on your Odin codebase:
| Tool | What it does |
|------|-------------|
| `codegraph_search` | Find symbols by name |
| `codegraph_context` | Get code context relevant to a task |
| `codegraph_callers` | What calls a function |
| `codegraph_callees` | What a function calls |
| `codegraph_impact` | Transitive impact of changing a symbol |
| `codegraph_node` | Full details + source for a symbol |
> **Note**: Do not run `codegraph init` on an Odin project. CodeGraph does not support Odin and will hang trying to pre-load its WASM grammars. `olt --codegraph-init` is the correct entry point.
---
## Architecture
```
┌─────────────────────────────┐
│ olt │
│ argv[0] / subcommand │
│ dispatch │
└──────┬──────────┬───────────┘
│ │
┌────────┴──┐ ┌────┴──────┐
│ olt lsp │ │ olt mcp │
│ (editor) │ │ (agent) │
└────────┬──┘ └───────────┘
│
shared rule engine
analyze_content()
│
C001–C203 rules
```
Symlinks created by `olt setup`:
- `ols → olt` — IDE OLS integration (argv[0] dispatch → LSP mode)
- `olt-lsp → olt` — backward compat
- `olt-mcp → olt` — backward compat
---
## Project layout
```
src/main.odin Unified entry point (argv[0] + subcommand dispatch)
src/core/ Rule engine, CLI, config parsing, graph DB
src/mcp/ MCP server tools
src/lsp/ LSP proxy
ffi/tree_sitter/ Tree-sitter grammar + static libraries
ffi/sqlite/ SQLite static library
vendor/odin-mcp MCP protocol library (https://github.com/RainerXE/odin-mcp)
tests/ Rule test fixtures
scripts/ Build and test scripts
```
---
## Contributing
Run the full test suite before submitting:
```bash
./scripts/run_c001_tests.sh
./scripts/run_c002_tests.sh
# ... see scripts/run_*.sh for all rule suites
./artifacts/macos-arm64/olt src/ # must produce 0 violations
```
---
## Changelog
### 0.97.3 (2026-07-10)
- Fix installer issues: binary now properly installs to target directory
- Fix MCP configuration corruption issues
- Add backup/restore for existing configurations
- Improve error handling in installation process
## License
[MIT](https://en.wikipedia.org/wiki/MIT_License)
> "The miracle is this: The more we share the more we have." — Leonard Nimoy
