Fresh start every iteration
Every pass begins with a clean context window, so no stale conversation carries into the next task. What the agent needs is loaded from files, not recovered from a long chat history.
Open sourceCLIMIT
It forgets the chat on purpose.
Most autonomous coding loops fall apart on a real repository. As the run gets longer, context rot sets in: the model’s judgment degrades and “done” becomes whatever the agent says it is. Rather than fight that with a bigger context window, Felix throws the context away each iteration, keeps progress on disk, and will not move on until your tests, types, and builds pass.
A known technique, hardened for real repos.
The core loop is the Ralph technique: restart the agent with a clean context window every pass, and let files and git carry the state instead of the conversation. It works because persistence beats orchestration. Felix is that loop hardened for production: planning and building are separate phases, memory is structured artifacts you can read, and the repository’s own tests, types, and builds decide whether a task is actually done.
Read the repoNaive loop
The chat log is the memory
- Context rot degrades it as the chat grows
- The agent declares itself done
- A restart means starting over
Prompt-only harness
Quality is a suggestion
- Tests live in the prompt, not the loop
- Planning and building blur together
- Nothing durable to inspect later
Felix
The repo is the judge
- Each iteration starts with a fresh agent
- Progress is files, not a transcript
- Tests, types, and builds are hard gates
A loop steered by your own checks.
You write a requirement. Felix plans, then builds one task at a time. After each task it runs your checks. Fail, and the loop pushes back. Pass, and it commits and continues.
The loop
specs/
Requirement
No code yet
Plan
Then stop
One task
Gate, not a hint
Your checks
Fail, and it stays. Pass, and it commits and takes the next task.
One iteration
- 01Start a fresh agent
- 02Read the files, not the chat
- 03Do one task
- 04The repo decides
Nothing useful lives in the conversation. The next loop opens the files.
How it actually works
Progress lives on disk
This is context offloading: state lives in specs, plans, diffs, logs, and reports rather than the prompt. You can read it, share it, or resume the loop after a crash.
Checks are gates, not polish
Your test command, type-check, and build have to pass before the loop moves on. That backpressure is what steers the run.
Optional team view
Local by default. Turn on sync and the same artifacts show up on runfelix.io, so a team can watch runs without sitting on the machine.
A short walkthrough
Point Felix at a repository that already has tests. That case is what it is built for.
- 01
Set it up in the repo
felix setup creates the folders, picks an agent you already have installed, and records the command that should fail if the code is wrong.
- 02
Write a requirement
A spec in specs/ is the job: a standing test suite, not a to-do that gets crossed off and forgotten.
- 03
Felix plans, then builds
First it writes a plan. Then it takes one task, implements it, and stops to check. Planning is not allowed to sneak in code.
- 04
The checks decide the next move
If the tests fail, the loop stays on that task. If they pass, Felix commits and takes the next one, until the requirement is actually done.
What it is for
Use it when you want an agent on a real codebase, and you already have a way to tell whether the change is good.
Selected uses
Existing repositories
Mature codebases with tests, types, and a build that already means something.
Unattended loops
Leave it on a requirement. It runs until the work is done, or until the checks keep failing and it stops honestly.
Parallel workers
Several requirements at once, each in its own isolated worktree, then merged back when the checks pass.
Team visibility
Mirror run artifacts to runfelix.io when you want a shared history beyond one laptop.
The agent you already use
Claude, Copilot, Gemini, Codex, Droid. Felix is the loop around them, not another model.
That an agent reporting success is evidence of success.