Aletheia
“What an agent says happened is not always what happened.”
A small experiment in making coding agents check their work
> claim ..... done > tests ..... 12 passed > diff ...... 4 files > verdict ... VERIFIED
- Project
- 01
- Category
- Developer tooling
- Year
- 2026
- Status
- Working prototype
- License
- Apache-2.0
- Built with
- Python 3.11+
I kept running into the same small annoyance: a coding agent could give a confident summary while the change still failed a test.
That made me curious about the boundary between an agent doing work and an agent judging its own work.
Aletheia is my attempt at that boundary. You give it checks to run, it records what happened, and it can return useful failure context to the agent. It is a working prototype, not a finished answer.
The order matters. Each step is what earns the next one the right to run.
- 01
You declare the checks
aletheia init --test 'pytest -q' --typecheck 'mypy src'. Commands are argv arrays, not shell scripts. No config guessing.
- 02
Your agent works normally
Claude Code, Codex, OpenCode, or any OpenAI/Anthropic-protocol runtime. Aletheia hooks into supported boundaries — it isn't another assistant competing for the prompt.
- 03
Checks run on completion
Tests, type checks and diff checks execute independently. Exit codes, output and timing are captured as evidence.
- 04
Failures are retained
Unsuccessful file contents go into a content-addressed checkpoint before any rollback. The failure stays inspectable rather than vanishing.
- 05
Recovery is bounded
Actionable failure context goes back to the agent within a fixed budget — so a loop either converges or stops honestly.
Claims, and how you'd check them
A claim without a way to test it is marketing. Each of these has a method.
Verification runs independently of the agent's completion claim
check · Governed by your configured commands, not by anything the model reports
Failed states survive the rollback
check · Content-addressed checkpoints, previewable in the read-only console
The console cannot act on your repository
check · It does not launch agents, run tests, restore files or change task state
Nothing leaves your machine
check · Local-first. No cloud account, no credential scraping. Your model provider may still need its own access
The scope of a tool is part of its honesty. These are the edges of Aletheia, stated by the person who wrote it.
- Not a coding assistant — it supervises one you already use
- Compatibility is explicit per integration, not a promise to observe everything
- No published PyPI package; install from the repository
- Linux and macOS only, and the supervised repo needs at least one commit
Avaira Protocol
An experiment in making agents pause when they are unsure