One file. Your AI coding agent becomes a scientist.
Researcher turns your coding agent into an experiment loop: you agree on a metric, and the agent tries one change at a time on its own branch, keeps what moves the number and reverts what does not.
Ask an agent to make something faster and it changes things and tells you it is better. You have no baseline and no record of what it tried, so you can't check that.
In Claude Code:
/plugin marketplace add krzysztofdudek/ResearcherSkill
/plugin install researcher@researcher-marketplace
Then run /reload-plugins or restart Claude Code. No config, no API key.
| Piece | Where it lands | What it does | When it acts |
|---|---|---|---|
The Researcher skill, one Markdown file (skills/researcher/SKILL.md) |
your Claude Code plugins | Runs the interview, sets up the lab and drives the loop. | On /researcher, or when you ask to make something measurable better. |
A branch research/<slug>, and more research/... branches when it forks |
your local git | One commit per experiment; a discarded experiment is removed with git reset --hard HEAD~1, its commit id kept in the log. |
During a run. |
.lab/ |
repository root, untracked | The config, results.tsv, the log, the branch registry, the parking lot of ideas, a scratch workspace and, at the end, a summary. |
From setup; it survives every git operation and lets the next session resume. |
Two lines in .gitignore |
your .gitignore |
Ignore .lab/ and run.log. |
At setup. |
.lab/bin/ helpers and your tool's ignore file (for example .claudeignore) |
.lab/bin/ and the repository root |
Keep each run's output short, to save tokens. | Only if you say yes to this in the interview. |
- Never touches: files outside the scope you agree on in the interview; it asks you when an experiment would need to. The skill has no step that pushes.
- Needs: git, and a way to measure: a command that prints a number, or a rubric you define together.
- Costs: the loop runs until you stop it or it reaches your target, unless you set a number of experiments. Each experiment runs your command, killed after the time budget you set (five minutes by default). With a rubric instead of a number, three evaluator subagents score each experiment.
- In the agent's context: the skill's description always; the body (about 3,300 words) when it runs; the lab files it re-reads before each experiment.
Other agents: GitHub Copilot CLI, Cursor, a plain skill folder
GitHub Copilot CLI:
copilot plugin marketplace add krzysztofdudek/ResearcherSkill
copilot plugin install researcher@researcher-marketplace
Cursor:
git clone https://github.com/krzysztofdudek/ResearcherSkill.git
ln -s "$(pwd)/ResearcherSkill" ~/.cursor/plugins/local/researcher
Then Developer: Reload Window.
A plain skill folder: copy skills/researcher/SKILL.md to ~/.claude/skills/researcher/SKILL.md (user level) or .claude/skills/researcher/SKILL.md (project level), ~/.cursor/skills/researcher/SKILL.md for Cursor, or wherever your agent reads skills. Trigger it by asking for "researcher mode".
- Before any experiment, the agent asks what to optimise, how to measure it, what it may change and what is off limits, and reads the setup back for your yes.
- It records a baseline with no changes first.
- It commits before every experiment, logs the result, and keeps or resets the commit by the number.
- After three discards in a row it must write down why it continues; after five it forks to a different approach.
- When the session ends, the next one finds
.lab/and asks whether to resume or start fresh.
-
Install with the two commands above, then run
/researcherand say what you want better, for example "makenpm run buildfaster".You see: the interview: the objective, the metric and its command, the scope, the constraints, the run command, the time budget, and when to stop. Then a compact table of the setup to confirm.
-
Confirm.
You see: a new
research/<slug>branch,.lab/created, two lines added to.gitignore, and experiment 0, the baseline, in.lab/results.tsv. -
Let it work, and look in when you want.
You see: one entry per experiment in
.lab/log.md, each with its hypothesis, the change, the result against the best so far, and keep or discard. -
Stop it, or let it reach your target.
You see:
.lab/summary.mdwith the experiments per branch, the best result against the baseline, the changes that mattered most and the ideas left untested. The kept work sits on theresearch/branch for you to merge or not.
The guide walks through a complete run from start to finish.
- It does not invent a metric for you; if you can't measure the result, it builds a rubric with you, and a rubric is a judgment, not a measurement.
- It does not keep a change that did not move the number.
- It does not stop by itself unless you give it a target or a number of experiments.
- It has no step that merges its
research/branch into yours; that stays your call.
In Claude Code:
claude plugin uninstall researcher@researcher-marketplace
claude plugin marketplace remove researcher-marketplace
On Copilot CLI, copilot plugin uninstall researcher@researcher-marketplace. On Cursor, delete the link in ~/.cursor/plugins/local/researcher.
Then delete .lab/ (the whole experiment history), the two lines it added to .gitignore, the .lab/bin/ helpers and tool ignore file if you accepted them, and the research/ branches you no longer want.
Researcher is an add-on of the family: it attaches to the agent, depends on no other family tool and keeps its own version. It generalises the autoresearch loop beyond machine learning, to anything you can measure.
Read more: The guide · The skill · Changelog · Discussions · Report a problem
Jarl is the loop. Yggdrasil is the law. Grain is the survey. Those three are the core, and they ship under one version number, Jarl on it from 6.1.0: one set of tools built and tested against each other. Each of them works alone. Where a repository has a check, the check decides what lands in a Jarl loop: a fresh reviewer can only stop a change, never make a failing check pass, and its word is recorded as testimony. A Jarl loop in a repository with no check lands on testimony alone, and says so. Law that stays inside one component is raised freely by the agent working it. Law or decisions that reach a whole type of code are shared vocabulary: the agent proposes them and they run as advice at once, and the client — the one person the whole system answers to — admits them in one batch when the work closes. Only the client lowers or vetoes law. The core's shared machine contracts are registered on one page. The family is developed in the open in Althing: its releases, research and rulings.
Start at the step where it hurts.
| Where it hurts | Start with |
|---|---|
| More issues than one agent can hold in its head | Jarl |
| The agent keeps breaking what was agreed | Yggdrasil |
| Nobody knows what was agreed | Grain, which earns its keep the moment you are about to write law |
| Core | What it holds |
|---|---|
| Jarl | The loop. Everything seen becomes an issue, each issue gets one worker in its own worktree, nothing closes without evidence and a review, and no code closes without a fresh reviewer's word. Rulings keep their history, and a ruling about a whole type of code goes to the client in one batch when the loop closes. |
| Yggdrasil | The law. The architecture graph, the rules over it and the log of why, checked before the agent moves on and re-proved in CI without a key. A rule that reaches a whole type runs as advice until the client ratifies it. |
| Grain | The survey. Mines a repository's own code and history into a first graph — components, dependencies, and the rules the code already keeps, each with the count of places that break it today; Yggdrasil accepts it with one command. It measures and never blocks. |
Three add-ons attach to the agent rather than to the graph; each works alone, depends on nothing in the family and keeps its own version.
| Add-on | Stage | What it makes the agent prove |
|---|---|---|
| Ratatoskr | request → intent | Keeps the agent talking to you in plain words, not code, so you can follow what it's doing. |
| Urd | intent → code | When the spec is ambiguous, it consults the source of truth and asks, it doesn't guess. |
| Researcher (this one) | code → measured result | Point it at a metric and it runs experiments, hypotheses kept and discarded. |
MIT. Made by Krzysztof Dudek.
Questions? Open a discussion on GitHub.