Retornatus

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.

Retornatus mascot: a chrome AI agent in a black suit adjusting sunglasses, with a teal ouroboros serpent and an orange comet flame

Why people use it

How you use it

  1. Install the CLI and initialize it in your project.
  2. Open the project in Cursor, Claude Code, Codex, or your preferred agent.
  3. Describe what you want — Retornatus clarifies requirements, stages intake when needed, and agrees a finish line before the build sprint.
  4. Let the agent work under that agreement; check status anytime.
  5. 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”

Presets

retornatus init --preset writes a starting config from a file shipped in the package. verify checks that the named commands ran and exited 0. It does not grade the tests, the deploy plan, or the eval set.

python

Python 3.11+ tests and static checks: pytest, ruff, and mypy.

python-platform

Extends python. Ship and AI rules run when deploy files or model paths change.

fastapi

Extends python-platform. API layout globs. Alembic paths count as ship.

django

Extends python-platform. Django layout globs. Migration paths count as ship.

rag

Extends python-platform. Retrieval and prompt globs, with a stronger AI surface.

worker

Extends python-platform. Task and queue globs. Task code counts as ship and needs a retry note.

retornatus init --list-presets
retornatus init --preset fastapi

Ship means Docker, Compose, Terraform, Helm, or a workflow file. With worker, task, schedule, and queue files count as ship too. AI means prompts, evals, MCP, or retrieval code. If those paths are not in the Change, the extra rule is not required. An existing config stays put unless you pass --force-config. Presets guide.

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. On a pull request, the GitHub Action posts one sticky verdict comment. integrate --hooks can inject the active Change at session start and keep the turn open until that Change is SATISFIED. That hook is a guardrail. The pull-request check stays the source of truth. Agent hooks.

What’s new

Highlights from 1.9.1, including the subagent-stop hook, the scope warning hook, the SessionStart hook, agent hooks, and init presets.

Release notes and technical depth: documentation · releases.