Retornatus

Keep AI coding agents honest — with goals, memory, and proof.

Install once in your project. Your agent works toward a clear outcome, remembers across chats, and cannot call work “done” without evidence you can see.

Install Quick start

Seedcore — Retornatus mascot floating with a glowing proof crystal and energy trail

Why people use it

You stay in control. The agent proposes and builds; you keep the bar for “done.”
Chat stops being the only memory. Intent and progress live in the repo, so the next session (or teammate) can continue.
Fewer false finishes. Work closes when there is proof — not when the model sounds confident.
Right amount of ceremony. Tiny fixes stay light; risky work earns more structure.
Skills when you need them. Specialize for the problem at hand with current research — not a stale mega-pack.

How you use it

Install the CLI and initialize it in your project.
Open the project in Cursor, Claude Code, Codex, or your preferred agent.
Describe what you want — Retornatus turns that into a clear change with an agreed finish line.
Let the agent work under that agreement; check status anytime.
Close when evidence matches the goal — then the next return starts wiser.

Your coding agent still writes the code. Retornatus governs the loop and keeps the record. Deep mechanics live in the docs.

The idea in one breath

Govern the work. Bound the agent. Verify the outcome. Demand what you need, agree on what “done” means, execute, then verify with proof that stays in git — so every return to the project is informed, not amnesiac.

Without

Jumps to code and declares victory
Each chat starts from zero
You rediscover the same mistakes

With Retornatus

Clear finish line before the build sprint
Project memory survives the tab
Proof required before “done”

Install

uv tool install retornatus
cd /path/to/your-app
retornatus init
retornatus integrate
retornatus doctor

Needs Python 3.11+ · uv recommended · also on PyPI. Then open the project in your AI coding agent and start a change.

Read the quick start Star on GitHub

What’s new

One-screen progress — see goals, proof, and what’s next without digging through chat.
Health at a glance — quick checks that separate “process needs care” from hard stops.
Lessons that stick — a failed check can become guidance for the next return.
Seedcore — brand mascot for the site and README (original illustration).

Release notes and technical depth: documentation · releases.