Quickstart · Usage · How it works · The receipts · Headless · White paper
Agents that don’t just act.
They audit · verify · attack · and prove.
Jeffy Loop is an autonomous engineering system built around a simple principle: AI agents shouldn’t just produce work. They should produce evidence that the work is correct. Instead of asking an agent to complete a task and trusting its conclusion, Jeffy creates a continuous Audit → Attack → Verify → Prove loop in which specialized agents inspect the work, challenge it, validate the result, and generate an auditable record of what happened. The goal isn’t simply autonomous code generation; it is autonomous engineering with proof - where every claimed result is accompanied by reproducible evidence that can be independently examined.
Jeffy treats “done” as something that must be demonstrated, not declared. The system is designed to turn autonomous engineering from a conversational interaction into an evidence-producing process: actions leave traces, decisions have provenance, failures are exposed rather than hidden, and successful outcomes produce a durable receipt of what was changed, why it was changed, and how the result was verified.
Jeffy was run against widely-used open-source projects with no connection to this repository, each project's own test suite as the oracle, and every run published in full.
| Projects tested | Fixed | Failed to converge | PRs opened | PRs merged | Issues filed |
|---|---|---|---|---|---|
| 125 | 97 | 28 | 50 | 15 | 4 |
96 projects run to convergence across 13 languages with no language-specific analyzer or ruleset, and 34 attempts that did not converge, each with the budget it was given before it started and the reason it ran out. Three greenfield builds converged from empty directories under judges the loop could not edit.
A merged pull request is the one outcome the loop cannot award itself. Thirteen projects have merged its patches; four of them:
- bat - a just-merged security flag did nothing when piped; caught before it ever shipped.
- mimalloc - a documented zeroing allocator returned uninitialized heap memory above the small-size threshold; merged by the library's author.
- ada - the URL parser inside Node.js reported
host_endone byte short and truncated the host; merged forty minutes after filing. - PapaParse - header de-duplication re-ran after every resume and rewrote data in place; shipped in 5.7.0.
The full scorecard, every merged patch, and every failure, or the record of every attempt ever started.
Each one is enforced by the iteration prompt, the state files, or the Stop hook, and each is checkable in this repository. How they are enforced.
- It audits like an engineer, not a linter. Every run opens with a real audit; a finding exists only if the loop can point at it and prove it with a runnable check.
- It cannot wreck your repo. Every iteration ends in a local checkpoint commit, a verify gate reverts any iteration that breaks the project, and nothing is pushed.
- "Done" is not the agent's opinion. A declaration needs a clean audit, a fully swept surface inventory, and an adversarial evaluator's countersignature, all re-checked in shell.
- It cannot claim what it never looked at. The whole public surface goes on a checklist before any finding is filed, and a swept row reopens when its code changes.
- Lessons become machinery. A rule learned the hard way binds every iteration after it; the engine itself is held to 312 behavioural checks on Linux, Windows and macOS.
You need exactly two things. The installer handles everything else, including jq.
- Claude Code - installed and signed in once
- git - confirm with
git --version; otherwisewinget install Git.Git,brew install git, orsudo apt-get install git
Install Jeffy:
git clone https://github.com/lenamonj/jeffy-loop.git
cd jeffy-loop
./install.sh # Windows PowerShell: .\install.ps1Note
If PowerShell blocks the installer with "running scripts is disabled on this system", run it once with powershell -ExecutionPolicy Bypass -File .\install.ps1 - the bypass applies to that single invocation only.
The installer verifies the Claude Code CLI and jq (offering to install it via winget, Homebrew, or apt), copies the /jeffy and /cancel-jeffy skills - engine included - to ~/.claude/skills, and registers the loop's hook in ~/.claude/settings.json. Every step prints an [OK] or the exact fix.
Then open Claude Code in the project you want to improve and type /jeffy 10.
Tip
/jeffy is a slash command inside the Claude Code session, not a shell command.
When that run ends, close the session and start a new one to run it again. That restart is doing real work, and why is worth two minutes.
| Page | What it covers |
|---|---|
| Usage | Flags, rounds and budgets, scoped mode, cancelling, upgrading, uninstalling, and what to know before a first run |
| How it works | The run lifecycle, the five guarantees, the full rule set, what a converged stop looks like, and how the loop improves itself |
| Headless runs | Running budgeted rounds unattended from bash or PowerShell |
| The receipts | Every open-source target with its outcome, the merged patches, the greenfield builds |
| Contributing | The validator and the review bar |
| White paper | 32 pages for readers new to agent loops: how loops got here, every rule from first principles, and what this method still cannot do |
Important
Trust model. The entire engine is one auditable shell script in this repo (skills/jeffy/hooks/stop-hook.sh) plus the small library it sources from skills/jeffy/hooks/lib/, registered as a Claude Code Stop hook. It fires at turn end but exits instantly unless the current project has a live Jeffy state file naming that session - zero cost and zero behavior outside a run. The installer's only writes outside this repo are the two skill folders it copies into ~/.claude/skills (engine included), that one hook registration in ~/.claude/settings.json, and - only when jq is missing and you answer yes to its prompt - a jq install through your system package manager (winget, Homebrew, or apt).
MIT