THOTH

Local reliability layer for AI coding agents.

Git diff → impact analysis → relevant verification → evidence

AI coding agents (Cursor, Claude Code, Codex, …) can generate working code quickly — but a passing build or test run does not prove the whole change was verified. Thoth provides evidence about what was actually checked and explicitly identifies what remains unverified.

Alpha software. Interfaces may change. TypeScript/JavaScript only. macOS/Linux tested; Windows is not supported yet. Feedback via GitHub issues.

What it does

Given your current uncommitted change, Thoth:

1. diffs the working tree against HEAD (or another base),
2. builds a dependency/symbol graph to compute the blast radius,
3. runs the relevant checks your project already defines,
4. writes an evidence report separating verified, failed, and not verified.

It runs entirely on your machine: no cloud backend, no accounts, no telemetry, no hosted AI. Your source code never leaves your disk.

Install

npm install -g @openthoth/cli        # binary: thoth
# or without installing:
npx @openthoth/cli init

Requires Node.js ≥ 22.12 and Git.

60-second quick start

cd your-ts-project
thoth init        # detect the project, write minimal .thoth/config.json
# ...edit code, or let your AI agent edit it...
thoth impact      # what could this change affect?
thoth verify      # run the relevant checks, save an evidence report
thoth report      # review the saved report later

thoth impact

3 file(s) changed, 1 symbol(s) changed, 2 symbol(s) potentially affected
Blast radius: LOW (2 direct and 0 indirect dependents)
  Upper bound (conservative): 2 file(s)
  Symbol-linked:              1 file(s)
Risk:         MEDIUM (score 3)

Relevant tests
  - src/math.test.ts (imports-changed-file, high)

The upper bound counts every file that transitively depends on a changed file — on barrel-heavy repos it over-counts, deliberately. Symbol-linked is the tighter bound: files whose symbols actually reference the change. Add --explain to see the evidence trail behind each conclusion.

thoth verify

Checks executed
    ✓ Typecheck
    ✓ Tests

Verified
  ✓ Typecheck — `npm run typecheck` passed (project-wide)
  ✓ Relevant tests — 1 test(s) passed in 1 relevant test file(s)

Not proven
  ⚠ Lint — no matching package.json script or configured command
  ⚠ Other tests — tests outside the selected relevant set were not run

Result: VERIFIED WITH LIMITATIONS

Verdicts are explicit — never "safe": VERIFIED · VERIFIED WITH LIMITATIONS · CHECK FAILED · NOT VERIFIED · NO CHANGES. See docs/verification-model.md.

MCP for AI coding agents

thoth mcp setup            # exact snippets for Cursor, Claude Code, Codex
thoth mcp setup --write    # merge into .cursor/mcp.json / .mcp.json (safe)
thoth mcp status           # what is configured

The server runs locally over stdio and is bound to the repository it launches in. There is intentionally no arbitrary-shell tool — agents can only invoke the same trusted checks the CLI can. See docs/mcp.md.

Trust model

thoth verify executes commands discovered from package.json scripts or .thoth/config.json — without a shell, with timeouts and working-tree tamper detection. Thoth is not a sandbox: running it carries the same trust implications as running the repository's scripts yourself. See docs/privacy.md.

Scope and limitations

• TypeScript/JavaScript projects; Git required for impact/verify.
• Conservative dependency analysis — barrel-heavy graphs over-count (the symbol-linked count is the tighter bound).
• Dynamic imports, type-driven dispatch, and runtime behavior can't be proven — reported as unknowns, not guessed.
• Machine output (--json, MCP) carries schemaVersion: 1 and is a stable contract for the alpha.

Full list: docs/limitations.md. Thoth provides evidence about what was checked — it does not prove code is safe, does not catch every regression, and passing verification does not mean production correctness.

Docs

Getting started · CLI reference · MCP setup · Verification model · Privacy · Limitations

Development

pnpm install && pnpm check    # typecheck + lint + tests + build
node dist/cli/main.js --help

MIT · OpenThoth · Changelog