Aletheore

What is Aletheore about?

Aletheore delivers a local‑first, deterministic scanner that analyses a codebase and writes machine‑readable evidence (JSON). Every downstream feature – AI‑driven audits, PR reviews, MCP server queries, dashboards – must cite this evidence, guaranteeing that claims are grounded in actual file:line data.

How to use Aletheore?

# Install the CLI (recommended with pipx)
pipx install aletheore

# Run a full repository scan
aletheore scan .

# Query the generated evidence
aletheore query "Which packages have known vulnerabilities?"

# Compare two scans without re‑scanning
aletheore diff <scan1> <scan2>

# Start the MCP server (exposes 34+ tools for agents)
aletheore mcp

# Launch the local web dashboard
aletheore dashboard

The GitHub Action can be added to a workflow to automatically scan PRs and post diff‑based comments.

Key features of Aletheore

• Deterministic scanning – no LLM calls, no network traffic (except optional OSV/license lookups).
• Multi‑language support – Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, Kotlin, Ruby, PHP, C, C++, C#, Swift.
• Evidence‑grounded AI – audit can attach LLM‑generated reports to concrete evidence fields.
• MCP server – exposes symbol, dependency, ownership, dead‑code, hotspot, semantic‑search, and more as fast stdio APIs.
• Live dashboard – visualises dependency graphs, cluster maps, scan history trends.
• GitHub Action – scans PR base/head, posts new/removed secrets, vulnerability changes, and convention violations.
• Extensive test suite – 1,600+ tests, CI badge, coverage, and security scorecards.
• Benchmarks – public harness validates review quality against real open‑source PRs.

Use cases of Aletheore

• CI/CD security gating – run aletheore scan + aletheore diff on every commit to catch secrets or vulnerable dependencies before merge.
• AI‑assisted code review – integrate the hosted GitHub App to have LLM‑driven PR comments that cite concrete evidence.
• Internal code‑base documentation – generate AI‑written docs that are traceable to source symbols.
• Architecture mapping – use the AIRview feature (GitHub App) for an always‑current repo diagram.
• Developer tooling – agents (Claude Code, Cursor, VS Code extensions, etc.) query the MCP server for fast symbol look‑ups, ownership, or dead‑code detection.
• Compliance & governance – audit historical git ownership, secret sweep, and license checks without exposing code.

FAQ from the Aletheore

Q: Do I need an internet connection? A: Only for optional OSV vulnerability and license lookups; you can disable them for a fully offline run.

Q: Which package manager should I use? A: Install via pipx, which creates an isolated environment and adds the aletheore command to your PATH.

Q: Can I run the scanner in CI without an LLM? A: Yes. CI pipelines typically execute aletheore scan followed by aletheore diff; no LLM calls are made.

Q: How does the hosted GitHub App differ from the CLI? A: The CLI is free and runs locally. The App adds paid SaaS features like automated PR reviews, AIRview architecture maps, AI‑generated docs, and production monitoring.

Q: What license governs the code? A: Aletheore is released under the PolyForm Non‑commercial License 1.0.0 – free for personal/research use; commercial usage requires a separate license.

Q: How many tools does the MCP server expose? A: By default 34 tools (35 when ALETHEORE_MCP_ALLOW=external is enabled), covering symbol lookup, dependency graphs, ownership, clustering, dead‑code detection, hotspot analysis, full‑text and semantic search, and more.

$ pipx install aletheore
$ aletheore scan .

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.
• 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 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 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 34 tools by default (35 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 or re-reading files on 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 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.

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

Full command reference, MCP tool list, per-language import-resolution details, and configuration options: src/README.md.

Aletheore AIR (hosted GitHub App)

Everything above is the free, local-first CLI (Aletheore Community). Installing the Aletheore GitHub App adds a hosted layer on top of the same evidence — paid plans start at $29.99/mo for up to 3 team members (additional seats$6.99/mo each):

• Automated PR review — Flash reviews and managed audits comment directly on pull requests, scoped to the changed hunks, citing file:line evidence. Blast-radius checks trace a changed symbol to its real callers across the repo (or say plainly when no caller could be confirmed, instead of guessing).
• AIRview — an AI-generated, always-current architecture map of the repo, rebuilt from the same dependency-graph evidence scan produces.
• AI-generated Docs — per-symbol descriptions written straight from real source, drafted as PRs land and backfilled for a repo's existing public API, always marked as AI-generated rather than presented as hand-written.
• Production monitoring — live endpoint reachability/latency checks mapped back to the source handler that owns the route, with Slack/Teams alerts on state changes.
• Branch-protection checks and team seat management.

The GitHub App and dashboard code lives in github-app/; see its own README for deployment and operations details.

Repository layout

• src/ — the actual, working CLI code (see its README for everything above in detail).
• github-app/ — the hosted GitHub App: FastAPI server, RQ workers, migrations. See Aletheore AIR above for what it does.
• site/ — the marketing site (Next.js).
• docs/superpowers/ — design specs and implementation plans written during development.
• docs/operations/ — current operational baselines: incident response, data handling, SLOs, deployment verification, branch protection, support process.
• SECURITY.md — vulnerability reporting and response targets.

Related, separate repo: aletheore-benchmarks — the public PR-review benchmark harness and published results.

Licensing

Aletheore is licensed under the PolyForm Noncommercial License 1.0.0, not an OSI-approved open-source license. It's free for individuals: personal use, research, hobby projects, and evaluation. Any use for or within a company or other organization — including internal tooling at a company you work for — is a commercial use and requires a separate commercial license. Reach out at arihantkaul@outlook.com for commercial licensing, or see Aletheore AIR for the hosted, paid tier.

If it's useful to you personally, consider sponsoring development — no accounts, no tracking, nothing leaves your machine when you run it.