# aletheore: a repository scanner that has to show its work

> aletheore is a Python CLI, MCP server, dashboard and GitHub Action built around one rule: a deterministic scanner writes structured evidence, and every downstream feature, whether it is an AI audit, a PR bot or a wiki, has to cite that evidence or it does not get to make the claim. The scanner itself needs no account and no model, which is what makes it usable in a pipeline that cannot afford either.

**Aletheore/Aletheore** — Evidence-grounded repository audit CLI - deterministic scanner, MCP server, live dashboard, and a GitHub Action that posts PR diffs.

- Repository: https://github.com/Aletheore/Aletheore
- Website: https://www.aletheore.com
- Stars: 613 · Forks: 43
- Language: Python
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/aletheore-aletheore

## Evidence first, claims second

The design principle is stated in the README's opening section: code intelligence has to show its work. A deterministic scanner reads your repository and writes structured evidence, and every downstream feature, which the README names as the AI audit, the PR bot, the MCP server and the dashboard, has to cite that evidence or it does not get to make the claim.

That is a different architecture from the usual shape of these tools, where a model reads the diff and writes the review. Here the deterministic pass happens first and produces a machine readable artefact, and the model or the agent works from that artefact. The consequence for a finding is direct: a finding that cannot be verified against real evidence gets dropped or flagged, rather than shipped silently.

The result is that the tool is usable in two very different modes. A team that wants no model involvement at all can run the scanner, query the evidence and put the deterministic output in CI, and nothing about the pipeline requires an API key. A team that wants a written report can add a model on top, and the report still has to cite the evidence fields it used.

The homepage is aletheore.com, the package is on PyPI as aletheore, and the primary language is Python. The repository is not archived and the last push was on 2026-10-20, with three releases in the preceding eleven days, v0.9.27 on 2026-10-14 and v0.9.26 and v0.9.25 on 2026-10-09.

## What the deterministic scan actually reads

The scan output shown in the README lists the stages, and they are the real feature set of the scanner.

It detects languages, frameworks and build tools. It builds a module dependency graph by parsing source with tree-sitter. It analyzes git history and ownership. It scans the working tree for secrets. It checks dependencies for known vulnerabilities against OSV.dev. And it maps API endpoints.

```bash
$ pipx install aletheore
$ aletheore scan .
```

The output lands in a file inside the repository, at .aletheore/air.json, which is the artefact everything else reads. Keeping it in the repository tree is a deliberate choice rather than a temporary directory, because a file that is committed can be diffed between commits, which is what the diff command later consumes.

The language coverage is broad and specific: Python, JavaScript and JSX, TypeScript and TSX, Go, Rust, Java, Kotlin, Ruby, PHP, C, C++, C# and Swift. The dependency graph is built by parsing source rather than by reading a lockfile, so it covers imports that never reach a manifest, and that is the same mechanism that lets the tool reason about ownership and about which modules are actually used.

The ownership analysis is worth singling out, because it is a source of signal that most scanners skip. Mapping who wrote which parts of a repository turns a dependency graph into something a reviewer can reason about, and it is also what makes the cluster view in the dashboard possible.

## No account, no key, and network access you can switch off

The README is explicit about the free tier, and the specifics matter for a security tool. The scan, query, diff commands, 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, which is on by default and can be turned off with one command, with the documentation for it in the source README under crash reporting.

The network access that does exist is narrow and named. The scanner reaches out to the vulnerability and licence registries, and the README says those lookups can be turned off too, for a fully offline run. That is the right shape for a tool that reads your source tree: a default that sends nothing anywhere, with two opt-in lookups and a crash report you can disable.

The model layer is separate and optional. The audit command has a coding-agent CLI or API provider write a grounded markdown report, and it works with six provider families, Claude, OpenAI, Google, Mistral, xAI or a local Ollama model, with your key, your cost and your choice. The README also states that you can skip the LLM step entirely and just use the deterministic evidence.

The GitHub App and the hosted offering sit on top of the same engine, and the README makes the trade explicit: install the app for hosted PR review, a dashboard and the AIRview docs, or keep using the free local CLI.

## Seven commands, and two of them never call a model

The command surface is worth taking one at a time, because the commands split cleanly by whether they need a model.

The scan is the deterministic scanner, and the README says it is safe to run in CI on every commit. The audit scans and then has a coding-agent CLI or an API provider write a full grounded markdown report citing exact evidence fields, and the README is explicit that it is meant to be run by hand against your own repository, pointing at the source README for why it is not wired into CI.

The query and diff commands answer a targeted question or compare two scans from existing evidence, with no re-scan and no LLM call needed. That is the cheapest way to use the tool, since the evidence is already on disk.

The mcp command starts a stdio MCP server exposing 36 tools by default, or 37 with ALETHEORE_MCP_ALLOW=external enabled, covering module, symbol and dependency lookups, ownership, clusters, dead code, hotspots, full text and semantic search, and triggers for scanning and indexing. The point of the server is that a coding agent can query the repository's structure directly instead of shelling out for every lookup, and it re-scans in the background as files change unless it is started with --no-watch. There is an mcp-install command that wires it into Claude Code, Cursor, VS Code, Kiro, Opencode or the Codex CLI automatically.

The tokens command measures how many tokens your coding agent re-reads on every turn and can trim the built-in tools a project does not use, which is reversible, project scoped and off by default. It also caps every repo wide tool without a target to a size budget, keeping the shape of an over budget result, saying what was left out, and offering section, offset, limit and filter parameters to page through the rest without loss.

## The GitHub Action posts a diff, never an audit

The action is the part of the project that touches other people's pull requests, and the design constraint is stated plainly: CI only ever runs scan and diff, which are fast and deterministic, never the full agent-driven audit.

The action, defined in action.yml and published on the Marketplace as Aletheore, scans a pull request's base and head refs and posts a diff. What is in that diff is specific: new and resolved secrets, dependency vulnerabilities, and layer-convention violations. It is delivered as a pull request comment, as inline annotations, and in the run's Step Summary.

The usage is the short YAML block, with the action pinned to a version and one option to fail the build.

```yaml
- uses: Aletheore/Aletheore@v0.7.2
  with:
    fail-on-new-secrets: true
```

The fail-on-new-secrets option is the one that changes behaviour rather than reporting, and it is the setting a security conscious team would reach for first.

Note the version in that example against the current release, which is v0.9.27. The README example was written for an earlier tag, and pinning the action to a version you have tested is the sensible approach, since the action's output format is what a reviewer reads.

The repository also documents a benchmarking approach, in a separate aletheore-benchmarks repository, described as a public harness testing review quality against real open source pull requests with blind LLM judging and a published methodology, comparing the evidence-grounded context against raw-diff and full-file-context baselines.

## A noncommercial licence, and a repo that audits itself

The licence is the one thing to read before anything else. The badge in the README names PolyForm Noncommercial 1.0.0, the project is recorded as using a custom licence that GitHub cannot classify, and the terms live in a LICENSE file at the top of the repository. A PolyForm noncommercial grant is not a permissive open source licence, and for a company that is a boundary rather than a detail. Nothing about the tool's quality changes that; it changes who may use it and on what terms, so the file itself has to be read before adoption, and the answer is not something the README summarises for you.

The rest of the repository is a good picture of how the project is run. There is a .aletheore.json at the top level, which is the tool's own configuration file in its own repository, and a schemas/ directory, which is where the evidence structure is defined. The src/ directory holds the implementation and the source README with the full command reference, the MCP tool list, the per language import resolution details and the configuration options. There is a github-app/ directory for the hosted app, a site/ directory, a docs/ directory, and a STARTUP_AUDIT_REPORT.md at the top level, which appears to be a scan of the project itself.

The package.json is for the repository's own tooling rather than the tool, since the tool is Python. It configures prettier for formatting the workflow files, markdownlint for the documentation, lychee for link checking, and cspell for spelling, with pinned versions and dependency overrides for js-yaml, smol-toml and katex.

The sharpest line in that file is the licence check, which runs pip-licenses with a fail-on for GPL and AGPL in both src and the github app. The project will not build with a copyleft dependency in its own tree. That is a deliberate policy, and it is worth knowing about before you try to add one.

## Conclusion

aletheore fits a team that wants deterministic repository evidence it can run on every commit, with an optional model layer on top, and it does not fit a commercial deployment, since the badge names PolyForm Noncommercial 1.0.0 and the repository carries no classification GitHub recognises. Before adopting it, read the LICENSE file, run aletheore scan . against a repository you control, and inspect the .aletheore/air.json output before letting any generated claim reach a pull request.

## FAQ

### What does aletheore scan do?

It detects languages, frameworks and build tools, builds a module dependency graph by parsing source with tree-sitter, analyses git history and ownership, scans the working tree for secrets, checks dependencies for known vulnerabilities through OSV.dev, and maps API endpoints. The result is written to .aletheore/air.json inside the repository.

### Does aletheore need an account or an API key?

No. The scan, query and diff commands, the MCP server and the local dashboard need no account and no API key, and nothing leaves your machine apart from a crash report you can turn off. The network lookups against the vulnerability and licence registries can also be disabled for a fully offline run.

### Which languages does aletheore support?

The README lists Python, JavaScript and JSX, TypeScript and TSX, Go, Rust, Java, Kotlin, Ruby, PHP, C, C++, C# and Swift, with per-language import resolution details documented in the source README.

### What licence does aletheore use?

The README badge names PolyForm Noncommercial 1.0.0, and the project is recorded as using a custom licence that GitHub cannot classify, with the terms in the LICENSE file at the top of the repository. Because the grant is noncommercial, that file is the thing to read before adopting the tool in a commercial setting.

### What does the aletheore GitHub Action do in CI?

It scans a pull request's base and head refs and posts a diff of new and resolved secrets, dependency vulnerabilities and layer-convention violations as a PR comment, inline annotations and the run Step Summary. The README is explicit that CI only runs scan and diff, never the agent-driven audit, and the usage block sets fail-on-new-secrets to true.

## Sources

- [Aletheore/Aletheore on GitHub](https://github.com/Aletheore/Aletheore)
- [Issues](https://github.com/Aletheore/Aletheore/issues)
- [Project website](https://www.aletheore.com)
- [README](https://github.com/Aletheore/Aletheore/blob/master/README.md)
- [Releases](https://github.com/Aletheore/Aletheore/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aletheore-aletheore