Empirica plugin
A Claude Code plugin with hooks and 26 skills: measures what the agent knows, blocks edits until code is read, keeps memory
- 255 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Hooks block file edits until the agent passes the gate
- A machine-wide setup changes Claude Code settings in `~/.claude`
- Session memory accumulates findings about your code in the `.empirica` folder
Install
- Works in
Manual install
pip install empirica && empirica setupInstalls the package and configures hooks, Sentinel, the system prompt and the status line for every Claude Code session on the machine. For one repository: empirica setup --scope project.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks block file edits until the agent passes the gate
- A machine-wide setup changes Claude Code settings in `~/.claude`
- Session memory accumulates findings about your code in the `.empirica` folder
This is third-party code. Review the repository files before installing.
What it does
Empirica works beside the model and records what its work rests on. Before an edit the agent investigates the codebase, and the Sentinel gate blocks changes until understanding is shown. Findings, dead ends, assumptions and mistakes live in a four-layer memory with provenance and confidence: wrong items are retracted or superseded, and the next session starts with what matters, not a summary. The CHECK threshold depends on the domain and how critical the work is, then tightens by the calibration of the model itself. Results are judged three ways: the agent's self-assessment, observations from deterministic checks and a reasoned grounded state. In the terminal a status line shows the stage, confidence, open goals and unknowns. Setup installs the hooks, Sentinel, system prompt and status line and adds 26 skills that load lazily, for example `/pre-publish` before a release and `/forecast` for choosing the next step. The CLI has over 240 commands, but a person does not need to learn them.
Who it is for. Developers and teams who trust Claude Code with long tasks and want to see how well the agent understands code before it changes it.
Good fit when
- The agent often edits files without understanding the architecture and you want a barrier before changes
- Work runs across many sessions and context is lost in each recap
- Before a release you want a consistent quality sweep that hunts for defects which pass the tests
- You want to see the agent's current confidence and the number of open questions in the terminal
Not a fit when
- You need a quick one-file fix: the gate demands investigation before a change
- Your main agent is neither Claude Code nor Codex: other harnesses are untested
- You do not want changes in `~/.claude`: setup is machine-wide by default and can be limited to one repository with `--scope project`
Example request
Fix the authentication bug in the login flow, but investigate the code first and show what you understoodLimitations
Python 3.10 or newer is required. Full integration is verified only for Claude Code; Codex needs the separate ecodex wrapper and the author calls other harnesses untested. A machine-wide setup writes hooks, a system prompt and a status line into `~/.claude` and affects every session. The Sentinel gate changes the usual flow: the agent investigates and logs findings first, so short tasks take longer. The network mode that links agents through Cortex is enabled separately and is off by default.
How to disable. `empirica setup --uninstall` only shows a removal plan. `empirica setup --uninstall --apply` removes the hooks, prompt and listener service, editing only its own keys in your settings. For a single-repository install add `--scope project`.
FAQ
How do I install Empirica for Claude Code?
Run `pip install empirica`, then `empirica setup`. Hooks, Sentinel, the system prompt and the status line configure themselves. On macOS there is an alternative: `brew tap empiricaai/tap` and `brew install empirica`.
What does the Sentinel gate do?
It blocks edits until the agent has shown that it understands the code involved. The threshold depends on domain and criticality: security is stricter than the default.
Can I limit Empirica to one project?
Yes, run `empirica setup --scope project` inside the repository. Hooks go to `.claude/settings.local.json` and `~/.claude` stays untouched.
Does the project have a cryptocurrency?
No. The project description says any token named Empirica, including $EMPIRICA on Solana, has nothing to do with the project.
Does it work with Codex?
Yes, through the separate ecodex wrapper, which loads the plugin itself. For Codex `empirica setup` refuses to write files.
Discussion
No questions or reviews yet.
Related
Pluginsclaude-mods adds 112 skills, 3 agents and 3 commands to Claude Code: stacks, agent operation, defense, session continuity.
A self-improvement plugin for Claude Code, Codex and OpenCode: turns corrections into rules the agent follows in later sessions
A Claude Code plugin that makes the model finish the job: result verification, evidence and systematic investigation enforced as procedure
A plugin with six working skills and a prompt library: routing a task to a prompt, pre-commit checks and skill audits.
A plugin for long Claude Code runs: context, cache and progress at a glance, with handoff to a fresh context before it fills.
Memory for Claude Code: hooks record human and agent decisions, and a grade is assigned afterwards once the outcome is known.
README in short
The description starts with the problem: agents remember a recap instead of facts, never retract mistakes, act before they understand and nobody grades their confidence against results. A capabilities table, installation, the status line, 26 skills, an optional network of peer agents and a supported-harness table follow.