Skip to content
v6.3.0MIT

Skill that turns your coding agent into the director of a feature branch: an issue loop (kept out of git by default, committed when you ask) where everything seen becomes an issue, a worker per issue works in its own worktree, evidence and a fresh review decide what closes, and a branch loop leaves no trace on main.

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.

PieceWhere it landsWhat it doesWhen it acts
The Jarl skill, /jarlyour Claude Code pluginsMakes 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 serverthe pluginEvery 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/.gitignoreThe 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 worktreesyour local gitOne per piece of work: a single issue, or a package of small neighbouring issues.While the issue is in progress.
Merge commitsyour feature branchThe 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 ygThe 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 main and 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 resume and 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 clears setting names who clears an issue instead (fresh, the owner, a named bot, or several reviewers who must approve together). status and report say 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

  1. 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.

  2. 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.

  3. 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 to main and 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 in goal.md and the check decides what lands.
  • Without a Check: line the loop lands on the reviewers' testimony alone, and status and report say 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 hurtsStart with
More issues than one agent can hold in its headJarl
The agent keeps breaking what was agreedYggdrasil
Nobody knows what was agreedGrain, which earns its keep the moment you are about to write law
CoreWhat 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.
YggdrasilThe 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.
GrainThe 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-onStageWhat it makes the agent prove
Ratatoskrrequest → intentKeeps the agent talking to you in plain words, not code, so you can follow what it's doing.
Urdintent → codeWhen the spec is ambiguous, it consults the source of truth and asks, it doesn't guess.
Researchercode → measured resultPoint it at a metric and it runs experiments, hypotheses kept and discarded.

License

MIT. Made by Krzysztof Dudek.