Jarl
Organises the work of coding agents, from one session to weeks of them. Your feature branch has more issues than one agent can hold in its head, so it fixes one, forgets two, and loses the third in the diff. Jarl makes the agent direct a crew instead of working alone.
On a feature branch, the agent files everything it sees as an issue, gives each piece of work one worker in its own worktree, and closes nothing without proof of its lines and an approval, from a fresh reviewer when the issue carries code, unless the loop's done gate asks no approve and a merge is enough, or the owner waives the review.
What you install
In Claude Code:
/plugin marketplace add krzysztofdudek/JarlSkill
/plugin install jarl@jarl-marketplace
Then run /reload-plugins or restart Claude Code. Needs Node.js 22 or newer on your PATH; no config, no API key.
| Piece | Where it lands | What it does | When it acts |
|---|---|---|---|
The Jarl skill, /jarl | your Claude Code plugins | Makes the agent the jarl of the branch: it files, schedules, raises workers, has them reviewed and merged. | When you run /jarl <goal>, or a session starts in a checkout that already has .jarl/. |
The jarl MCP server | the plugin | Every command of the tool as an MCP tool (jarl_resume, jarl_status, jarl_new and the rest), the writing ones included. | Started with the session. |
.jarl/ | root of your main checkout; by default ignored by git through its own .jarl/.gitignore | The goal, the issues, the rulings, the questions to you and the log of every move. | From the first /jarl until the loop closes. |
| Worker branches and worktrees | your local git | One per piece of work: a single issue, or a package of small neighbouring issues. | While the issue is in progress. |
| Merge commits | your feature branch | The merger merges each approved branch with a commit that names the issue, then runs the check on the result. | After a fresh reviewer approves. |
| Entries in Yggdrasil's logs | .yggdrasil/, only when the repository has a graph and a working yg | The rulings about a whole type of code that you ratified at close, written with yg log add. | At close, after your yes. |
- Never touches: it never merges into
mainand never pushes; merging and pushing wait for your word. By default the loop leaves no trace in the branch's history. - Needs: Node.js 22 or newer and git. Nothing else from the family.
- Costs: no key and no service of its own. Every worker, reviewer and merger is an agent run on your account.
- In the agent's context: the skill's description always; the skill body and the references it links when the loop runs; the MCP tool list.
Other agents: GitHub Copilot CLI, Cursor, Codex, a plain skill folder
GitHub Copilot CLI:
copilot plugin marketplace add krzysztofdudek/JarlSkill
copilot plugin install jarl@jarl-marketplace
Cursor:
git clone https://github.com/krzysztofdudek/JarlSkill.git
ln -s "$(pwd)/JarlSkill" ~/.cursor/plugins/local/jarl
Then Developer: Reload Window.
Codex reads a skill folder from ~/.agents/skills/jarl/ (user level) or .agents/skills/jarl/ (project level): copy the whole skills/jarl/ directory there, references/ included.
Cursor reads one from ~/.cursor/skills/jarl/ (user level) or .cursor/skills/jarl/ (project level): copy the whole skills/jarl/ directory there, references/ included.
A plain skill folder: copy the whole skills/jarl/ directory, references/ included, to ~/.claude/skills/jarl/ (user level) or .claude/skills/jarl/ (project level), or wherever your agent reads skills. To use the MCP tools with a copied folder in Claude Code: claude mcp add jarl -- node /absolute/path/to/skills/jarl/scripts/jarl-mcp.mjs. Without them the skill uses the command line.
What changes on the first day
- Everything anybody sees becomes an issue before anything is touched, so there are no fixes on the side.
- Each acceptance line says how it is proved: a test, a command, a comparison, a reader's judgement, or the owner. Exactly that method is carried out.
- Issues that touch the same files run one after another; the rest run in parallel.
- Each piece of work gets one worker in its own worktree, and a worker carries one issue or several small neighbouring ones.
- A worker's report counts as a claim until a fresh reviewer reads the diff and checks that the new test was red before the change and green after.
- One fresh reviewer takes each piece of work: it invents and runs scenarios the acceptance lines do not name.
- Once a branch is approved, the merger merges into the feature branch with a commit that names the issue and runs the check on the result.
- In the record, nothing is closed without an approve, from a fresh reviewer when the issue carries code.
- A line proved by a test, a command or a comparison also needs a recorded run of it; a line proved by reading needs none.
- The tool refuses an approve by a self (the issue's worker, anyone who has held its lease, or a worker of another issue on the same branch).
- The agent asks you when a protection would weaken, the goal would change, or work reaches outside the session.
- The next session runs
resumeand picks up from the files, not from memory.
Who clears an issue
The profile of the loop sets the done gate; every setting is in the profile reference.
- The gate follows the profile: a profile whose done gate asks no approve closes on recorded evidence and a merge in the base, which it must require.
- Beyond the approve, a profile can also require attached files before a kind of issue closes.
- A fresh reviewer's approve clears an issue unless the done gate's
clearssetting names who clears an issue instead (fresh, the owner, a named bot, or several reviewers who must approve together).statusandreportsay who reviewed the done work: fresh, waived by the owner (his ruling that waives the review), coordinator, self, relayed, bot, retracted when an approve was taken back and none stands, and unrecorded, then how many of every verdict recorded are relayed or a bot's.
Start
-
On a feature branch, run
/jarl make the export command handle every fixture in tests/fixtures.You see: the jarl writes
.jarl/goal.md, reads the fixtures and files what it finds as numbered issues, each with acceptance lines that say how each is proved. -
Let it run.
You see: issues that touch the same parser queued one after another, the others given one worker per piece of work, each in its own worktree, and each approved branch merged into your feature branch with a commit naming the issue.
-
When nothing is open, it closes the loop.
You see: the changelog carries every user-visible change, the suite is green on the tip, and
.jarl/is deleted. Merging tomainand pushing wait for you.
To keep the loop in git instead, open it with init "<goal>" --committed --by "<who>" (it travels with the branch) or init "<goal>" --permanent --by "<who>" (the repository keeps it as a record).
What it does not do
- It does not enforce architecture; that is Yggdrasil, the law beside this loop.
- It ships no machine gate of its own: where your repository has a check, name it with a
Check:line ingoal.mdand the check decides what lands. - Without a
Check:line the loop lands on the reviewers' testimony alone, andstatusandreportsay so at the top. - It records and displays; it never blocks code from landing.
- By default the loop lives only in the checkout that opened it; another clone does not see it.
Remove it
In Claude Code:
claude plugin uninstall jarl@jarl-marketplace
claude plugin marketplace remove jarl-marketplace
On Copilot CLI, copilot plugin uninstall jarl@jarl-marketplace. On Cursor, delete the link in ~/.cursor/plugins/local/jarl.
A closed loop has removed .jarl/ itself. For an open one, delete .jarl/ and the worker branches you do not want to keep. A committed or permanent loop is removed by a commit that deletes .jarl/.
Questions
Can the issues live in one repository while the code is in another? Yes: name the other repository when you file an issue (new "<title>" --repo "<name-or-path>" --by "<who>"), and the worker, the reviewer and the merger work there on its own feature branch.
Can a research report become issues? Yes: import "<findings.json>" --by "<who>" files one issue per finding, and a second run files nothing twice.
Where does Jarl look for the loop? At the root of a checkout, or of the main checkout from a worktree that holds none, and never in a subdirectory. A loop kept in one is reached with --root or an exported JARL_ROOT on the command line, with a tool call's root field or the server's JARL_ROOT, or for every call that follows with use "<path>". use alone lists the loops under the checkout, and where its root holds none and loops are below, a call that names none is refused with that list.
Can another tool read the loop? skills/jarl/scripts/record.mjs is the one stable surface to vendor, under the contract jarl-record/4 (the record as a library).
Where it fits
Jarl is the loop of the family, and it works alone: it touches Yggdrasil only to write the rulings you ratified into its logs, and only when a graph and yg are there.
Read more: The skill · The record · Commands and views · What Jarl will not grow · Changelog · Report a problem
The Yggdrasil family
Jarl is the loop. Yggdrasil is the law. Grain is the survey. Those three are the core, and they ship under one version number: 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 (this one) | The loop. Everything seen becomes an issue, each piece of work 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 | code → measured result | Point it at a metric and it runs experiments, hypotheses kept and discarded. |
License
MIT. Made by Krzysztof Dudek.