spar

Keep learning while AI writes the code.

Reviewing finished, convincing code teaches you almost nothing. You have no position to judge it from, so you read it, nod, and move on.

spar puts the position back. Before the agent writes anything, you say where the change belongs, how you would do it, and where it will break. Then it implements, shows you the difference, and writes down every place your model was wrong.

Those gaps pile up into a curriculum you never had to choose. The concept you miss most often rises to the top by itself, and the friction follows it there, so you never have to decide to work hard.

What it looks like

› add an endpoint for cancelling an order

  spar: level 2 (skeleton), 2 open gaps on "transaction boundaries in an ORM"

  Before I write anything:
    1. Where does this belong, and why there?
    2. How would you approach it? (two sentences)
    3. Where will this go wrong?

› 1. Orders controller, calling into the service
  2. load the order, set status, save
  3. no idea

  [writes the controller, the DI wiring and the error handling,
   and leaves the one line that matters]

  // TODO(spar: decide the transaction boundary. Who opens it,
  //             and what happens if the refund call fails halfway?)

You write those five lines yourself. Then spar done compares them against what the agent would have written and sorts each difference into one of three buckets: you misunderstood something, you mistyped something, or your version is better. Only the first two are logged as gaps.

Three weeks later, in the middle of unrelated work:

spar: one gap has come due. Ask them to explain "transaction boundaries in an ORM"
in their own words at the next natural pause. Do not show them the answer first.

Answering "no idea" is fine, by the way. It gets recorded as-is, and it is a strong enough signal that the next task touching that concept will ask more of you, not less.

Related MCP server: Learning Assistant MCP Server

Install

npm i -g spar-agent
spar install                                       # finds your agents, backs up, merges
spar setup --project /path/to/repo --stack ".NET"

That last line matters: nothing happens in a directory you have not named. A fresh install is completely inert. It will not even create ~/.spar until you point it at a project.

spar install is careful with files it did not write. It merges into what is already there, backs the file up first, and only ever replaces entries it put there itself. Run it twice and the second run changes nothing. Use --dry-run to see what it would do.

Where you stand

spar stats        # in the terminal
spar dashboard    # one self-contained HTML file

CALIBRATION, share of predictions that held, by week
  2026-07-13  ███████▁▁▁   67%     4/6   clean   mean level 2.3
  2026-07-20  ████▁▁▁▁▁▁   44%     4/9   clean   mean level 2.3
  2026-08-03  ████████▁▁   83%    10/12  clean   mean level 0.8
  2026-08-17  ██████████  100%     9/9   clean   mean level 0.3

CURRICULUM, concepts by weakness. The top row is what to learn next.
  * idempotency in webhooks              3 open / 3   box 1.3
    transaction boundaries in an ORM     8 open / 8   box 2.0
    EF change tracking                   0 open / 3   box 5.0

The number that matters is calibration: the share of your predictions that produced no misconception at all. Deliberately not a gap count, because a count only ever climbs, and would read as decline exactly while you get better.

Six weeks of a fictional .NET onboarding. The page follows your system theme.

The dashboard is a single file that never touches the network. No CDN, no web fonts, no chart library, and the charts are hand written SVG. Every number sits in the markup, so the page reads the same with scripting off, behind a strict CSP, or in an attachment preview. Script only adds multi select to the focus bar. It will still open, offline, from a double click, in five years.

There are no streaks, points or badges anywhere in it. In a tool where "no idea" is a useful answer, a counter would just teach you to fake competence.

Explaining with a picture

spar card --layout chain --title "Predict before you're told" \
  --subtitle "The gap between your guess and what was true is worth writing down." \
  --step "you:You predict" --step "agent:AI implements" --step "you:You compare"

One idea per card, written to ~/.spar/cards/. Four layouts cover most explanations: a chain of steps, a fan-out, a sequence between two parties, and a comparison.

The limits are enforced rather than suggested. More than five steps, more than three bullets, or a fourth colour role and the command refuses to render. That is deliberate, because the whole value of a small picture is that it stayed small, and a rule that only lives in a prompt drifts. If it will not render, the answer is two cards.

Colour marks what something is, never which step it is, so --step "you:..." keeps you the same colour on every card you make. cards.theme in ~/.spar/config.json picks the look: neon (the default, dark with outlined boxes) or plain.

The levels

At levels 2 and 3 the agent always leaves a failing test behind, and spar refuses the handover if it does not. A marker with no test hands you a guess and nothing to check it against, so the only way to find out whether you were right is to ask the agent, which is the dependency the whole tool exists to break. The test is what lets you work alone for twenty minutes and still know.

Set testCommand on a project and spar also runs the suite at handover and expects it to be red, because a test that already passes against an empty stub pins nothing:

spar setup --project "$(pwd)" --test-command "npm test"

That check is off by default. Running someone else's suite automatically is invasive and can be slow.

There is no off switch, only level 0. Your own gap log suggests the level and tells you why, and you can always overrule it. Overrules get counted, because someone constantly correcting the suggestion is telling you the thresholds are wrong.

Working a ticket in steps

spar plan --from docs/plan.md          # reads ## Task / ### Task headings
spar plan --step "..." --step "..."    # or name the steps yourself
spar plan                              # where am I
spar step done --session <id>

While a plan is active the step is the task. The gate fires once per step instead of guessing from silence, each step gets its own level from your gap log, and your prediction is attached to the step rather than the session, so it is still there tomorrow.

That granularity is the point. "Where will this go wrong?" is a real question about "add the cancel endpoint" and a guess about "implement cancellation with refunds", and a guess makes the calibration number stop measuring anything.

spar does not plan. Your agent reads the ticket and your planner breaks it up; spar decides how much of each step is yours. The plan lives in .spar/ in the project, and spar adds it to your .gitignore the moment it creates it.

What each agent gets

MCP is standardised where hooks are not, so the server reaches every MCP client without an adapter. The one thing it cannot do is the gate, because an MCP server offers tools and never intercepts the host's own writes. That limitation is the whole argument for maintaining per agent hook adapters, and the reason the voluntary tiers make a good trial but a poor substitute.

Installing it as a plugin

/plugin marketplace add Lander-Parren/spar

That offers two plugins. spar is this repo. humanizer is optional and not mine: it is blader/humanizer, MIT, Copyright (c) 2025 Siqi Chen, pinned to a specific commit rather than tracking its main branch.

It is listed alongside spar rather than copied into it, so it updates from its own repository and keeps its own author. The reason it is there at all: spar spends its whole life explaining something to a person who is still confused, and an explanation that reads as machine-written is the fastest way to lose them. spar's own skill carries a short version of that rule for people who do not install it.

What it will not do

Everything stays on your machine, in ~/.spar/. No account, no telemetry, no network calls, no API key of its own. The log holds concepts and misunderstandings rather than your business logic, which is what makes it safe to screenshot for a colleague.

And it fails open, always. A missing binary, a corrupt config, a bug in its own code: the gate opens and you carry on. A learning tool should never be the reason you cannot ship.

Once per task, not once per file. Fifteen edits behind one prediction is one gate.

It watches shell commands as well as write tools, because an agent reaches for cat > file <<EOF or perl -0pi far more often than for a dedicated write tool, and some setups tell it to prefer exactly that. A shell command is only stopped when it actually writes somewhere inside a tracked project: redirects, tee, in-place sed and perl, cp and mv destinations, and interpreter one-liners that open a file for writing. Reads and test runs go through untouched. Shell is not parseable by regex, so this is deliberately conservative and misses exotic forms rather than stopping ordinary work.

A task stays alive as long as there is movement in it, and lapses after 30 minutes of silence (idleMinutes in ~/.spar/config.json). That measures idleness rather than age, so a long careful task never gets interrupted halfway through. If you are starting something new before the timer runs out, spar next --session <id> re-arms it immediately.

The bias is deliberate. Re-arming on a follow up costs you thirty seconds and nudges you towards spar rush, which is how these tools die. Missing one task costs a single gap, and that concept will come round again.

One gap returns at session start, phrased as a question for the next natural pause. Never a queue, never an interruption. Answer it well and it moves up a box (1, 3, 7, 16 and 35 days). Answer it badly and it starts over tomorrow.

There is no separate app and no inbox to ignore, because it arrives in the session you were already working in.

Trying it without risking anything

example/ is a small TypeScript project with no dependencies, built to be pointed at.

cd example
spar setup --project "$(pwd)" --stack "TypeScript"

Then ask your agent to add order cancellation and watch the gate stop it. example/README.md explains what to look for.

Where the instructions live

A command emits facts. The skill says what to do with them. spar done prints a diff; what counts as a misconception rather than a typo is in the skill. The gate reports that a task has not been gated and names the commands; why you predict first is in the skill.

That split exists so the procedure can be read by any skills-capable client and changed without a release. For agents that cannot load skills, spar guide <topic> prints the same sections out of the same file:

spar guide                       # list the topics
spar guide the-closing-review

One source, two ways to deliver it, so the two cannot drift apart. A test asserts every section a hook points at actually exists, which means renaming a heading breaks the build rather than sending someone to a page that is not there.

npm install
npm test              # spar's own suite
npm run build
npm run emit          # regenerate the checked-in hook configs
npm run validate:example   # drive every hook end to end against example/

validate:example is the one that catches wiring problems. The unit tests prove the pieces; that script proves a real hook payload produces the decision it should, in a throwaway home, against the built binary.

The same hook definition is checked in three times over: Claude Code's plugin layout, the Agent Plugins namespace, and Cursor's. The two standards disagree about where client specific files belong, so there is no single location that satisfies both. All three are generated from src/core/hookconfig.ts by npm run emit, and a test fails the moment they drift apart.

License

MIT