Empirica is not a separate app. It runs inside your AI coding tool and changes how the AI works: it keeps a track record of what it has done, and it has to understand a problem before it is allowed to act on it. The core framework is open source and free. This page gets it running.
Install
pip install empirica
# 2. wire it into Claude Code
empirica setup-claude-code
The setup command installs the plugin, the gate that holds the AI back until it is ready, and a status line in your terminal that shows where you are at a glance. It is added next to your existing configuration, not over it. That is the whole install.
Claude Code is the fully supported tool today. The core CLI works anywhere; the plugin, the gate, and the status line are Claude Code specific for now.
Three steps, then you are working
Install the framework
One pip install. The open-source core: the CLI, the local record, and the discipline that runs inside your AI tool.
Wire it into Claude Code
One setup command installs the plugin, the gate, and the status line. It sits alongside your existing setup without overwriting anything.
Just work
Talk to your AI the way you already do. The framework keeps the record and runs the checks behind the scenes.
What changes when you work
You will not type framework commands. The AI does that for itself. What you notice is the shape of a piece of work: it understands first, a gate confirms it is ready, then it acts, then it measures what it learned. Empirica calls the first two the thinking and acting phases.
It understands before it touches anything
Reading and searching are always allowed. Editing and writing are held back. The AI explores, and records what it finds and what it is still unsure of.
A gate checks it is actually ready
Before it can change anything, the AI has to show its confidence is grounded in what it found, not in a guess. If it is not ready, it keeps investigating. This gate is the Sentinel.
Then it acts, and the work is tracked
Now it edits, writes, and commits. Goals and decisions are recorded as it goes, so the work is measured, not just done.
It measures what it learned
When the work is done, it re-checks its own state. The change from start to finish is graded against real evidence: did the tests pass, were the goals met. That is how calibration improves over time.
Your role is to steer
You guide it in plain language. It handles the bookkeeping.
"Let's understand the auth system before we change anything."
It investigates and logs what it learns, without touching files yet.
"I think we know enough. Let's implement."
It confirms it is ready, the gate opens, and it starts writing.
"That approach won't work, note it."
It records the dead end so it is not tried again later.
"Good. Commit and close this off."
It commits, then measures what actually got learned against the evidence.
Installing it is the start, not the point
The install gives you the track record and a memory that survives between sessions. The real leap comes from working this way on purpose: making the AI understand before it acts, letting the record build, and using its calibrated confidence to know when to trust it and when to dig deeper. That is a different way of working with AI, and it is where the gains compound.
See how a piece of work is structured →Running more than one AI, or a whole team? The open framework is the foundation. When you are ready to coordinate and govern a fleet, that is what Cortex and the extension add on top.
Ready to go deeper?
Read how it works, or browse the open-source code.