Scanning /path/to/your/repo... → Detecting languages, frameworks, and build tools → Building module dependency graph (parsing source with tree-sitter) → Analyzing git history and ownership → Scanning working tree for secrets → Checking dependencies for known vulnerabilities (OSV.dev) → Mapping API endpoints → Done ✓ Scan complete Evidence written to /path/to/your/repo/.aletheore/air.json
No LLM call, no account, no network access beyond the vulnerability/license registry lookups
(turn those off too for a fully offline run). That one command gets you a real dependency
graph, secrets scan, git-history secret sweep, dependency-vulnerability/license check, and
static API endpoint map — for **Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, Kotlin,
Ruby, PHP, C, C++, C#, and Swift**.
## Why
- **Grounded, not vibes.** Every AI-written claim (the `audit` report, PR review comments, the
architecture wiki) is checked against the file:line it cites. A finding that can't be
verified against real evidence gets dropped or flagged, not shipped silently.
- **The free tier is actually free.** `scan`, `query`, `diff`, the MCP server, and the local
dashboard need no account and no API key. Nothing leaves your machine, apart from a crash report
if the CLI itself crashes (on by default, one command to turn off; see
[Crash reporting](src/README.md#crash-reporting)).
- **Bring your own model, or don't use one at all.** `audit` works with six provider families
(Claude, OpenAI, Google, Mistral, xAI, or a local Ollama model) — your key, your cost, your
choice — or skip the LLM step entirely and just use the deterministic evidence.
- **1,600+ tests**, real CI, and a GitHub Action that dogfoods itself on every PR to this repo.
- **Benchmarked, not just claimed.** [aletheore-benchmarks](https://github.com/Aletheore/aletheore-benchmarks)
is the public harness we test review quality against — real open-source PRs, blind LLM
judging, and a published methodology, comparing Aletheore's evidence-grounded context
against raw-diff and full-file-context baselines.
## What's actually shipped
- **`aletheore scan`** — the deterministic scanner above. Safe to run in CI, on every commit.
- **`aletheore audit`** — scans, then has a coding-agent CLI or API provider write a full
grounded markdown report, citing exact evidence fields throughout. Meant to be run by hand
against your own repo — see [`src/README.md`](src/README.md) for why it isn't wired into CI.
- **`aletheore query`** / **`aletheore diff`** — answer a targeted question or compare two
scans from existing evidence, no re-scan or LLM call needed.
- **`aletheore mcp`** — a stdio MCP server exposing 36 tools by default (37 with
`ALETHEORE_MCP_ALLOW=external` enabled) (module/symbol/dependency lookups,
ownership, clusters, dead code, hotspots, full-text and semantic search, scan and index
triggers) so a coding agent can query your repo's structure directly instead of shelling out
for every lookup; it re-scans in the background as files change unless started
with `--no-watch`. `aletheore mcp-install` wires it into Claude Code,
Cursor, VS Code, Kiro, Opencode, or Codex CLI automatically.
- **`aletheore tokens`** — measures how many tokens your coding agent re-reads on every turn and, if you
choose, trims the built-in tools a project does not use (reversible, project-scoped, off by default).
Every repo-wide, no-target tool (dependency usage, environment variables, error handling, ...) caps
its result to a size budget by default — a result that already fits is untouched; an over-budget one
keeps its shape, says what was left out, and the same tool takes `section`/`offset`/`limit`/`filter`
to page through the rest losslessly.
- **`aletheore dashboard`** — a live local web UI: dependency graph, an Obsidian-style cluster
graph, trend charts across scan history, and the MCP tool list.
- **A GitHub Action** (`action.yml`, on the Marketplace as "Aletheore") — scans a PR's base and
head refs and posts a diff: new/resolved secrets, dependency vulnerabilities, and
layer-convention violations, as a PR comment, inline annotations, and the run's Step Summary.
CI only ever runs `scan` + `diff` — fast and deterministic, never the full agent-driven
`audit`.
```yaml
- uses: Aletheore/[email protected]
with:
fail-on-new-secrets: true