litmus

Never let a test plan slip. litmus is a Claude Code plugin that watches your edits, works out which test types the change likely needs, and — depending on the cadence you pick — either quietly reminds you or holds the turn until you've triaged a plan. It ships language-agnostic guides for nine test types and a /tdd skill.

litmus is not a linter and it does not grade the tests you write. It sits one step earlier: making sure test planning doesn't get forgotten, and injecting the right writing rules as context when you do write tests. For grading written tests, reach for /code-review instead.

It belongs to no vendor, phones home to nothing, and collects no telemetry.

How it works — three axes

The guides themselves are nine language-agnostic docs in guides/ — per-type must-cover cases and writing principles. The MCP server is one way to read them; you can also open the files directly.

What you'll see

When you change source and end a turn, litmus reminds you. In advisory mode it's a non-blocking note:

🧪 litmus — 2 source file(s) changed (140 lines) this session without a test plan.

Test types this change likely touches:
- Integration Test (high) — API endpoint change; persistence / DB change

Load a type's rules with the litmus get_guide tool (e.g. get_guide "regression"),
or read guides/ directly. Run /tdd to drive it test-first.

In block mode it holds the turn and walks you through a two-step triage instead:

STOP — litmus (block mode) requires a test plan before this turn ends.
Scope: 3 source file(s), 123 lines. Triage mode: FULL.

STEP 1 — TRIAGE (one markdown table, nothing else) ... then ask which types to detail.
STEP 2 — DESIGN (only the confirmed types) ... load each guide, extend existing tests.

The suggested types are regex-based guesses (from file paths and diff signals), tagged high/medium confidence — hints to confirm against the code, not verdicts. Editing a test file, or only docs/config, triggers nothing.

Test type map

Four levels, nine types:

Entry points by role

Install

Requires Node.js 18+ on your PATH — Claude Code runs the hooks and the MCP server with node.

/plugin marketplace add retemper/litmus
/plugin install litmus@retemper

Local development (point the marketplace at a local checkout instead):

/plugin marketplace add /path/to/litmus
/plugin install litmus@retemper

Run /reload-plugins (or restart Claude Code) to apply. On first use, litmus asks you two questions (cadence + forcefulness) and saves your answers. Until then it runs in its quietest useful mode.

Updating

Self-hosted marketplaces don't auto-update by default, so new versions won't arrive on their own. Either update on demand:

/plugin update litmus@retemper

…or enable auto-update once by adding the marketplace to your Claude Code settings.json:

{ "extraKnownMarketplaces": { "retemper": { "autoUpdate": true } } }

With that set, litmus updates itself whenever Claude Code starts. (Your personal config in ~/.claude/litmus lives outside the plugin cache, so updates never touch your settings.)

Configuration

Two knobs plus two thresholds.

cadence — when to nudge:

forcefulness — how to nudge:

Thresholds (only used by by-scale): minFiles (default 3) and minLines (default 80). A change at or under both is "light" and skipped by by-scale.

Where config comes from (highest precedence first)

1. Environment: LITMUS_CADENCE, LITMUS_FORCEFULNESS, LITMUS_MIN_FILES, LITMUS_MIN_LINES

2. Project: .litmus.json (searched from the cwd up to 8 levels)

3. Personal: ~/.claude/litmus/config.json

4. Unset

Safe defaults — litmus never goes silently dead:

• Fully unset → by-scale + advisory (the quietest mode that still speaks up).

• If you set cadence but not forcefulness, forcefulness defaults to block.

• To turn it off completely, set cadence: "off".

Example .litmus.json:

{ "cadence": "by-scale", "forcefulness": "advisory", "minFiles": 3, "minLines": 80 }

The block-mode workflow

In block mode the reminder isn't a warning — it's a 2-step triage that keeps a turn from dumping a wall of test cases:

1. Triage — one markdown table: each test type, needed? (✅/❌/🔶), a one-line reason, and any existing test path (you search first). Then it stops and asks which types to detail.

2. Design — only for the types you confirm, it reads that type's guide and writes cases — extending existing tests rather than duplicating them.

MCP tools

The plugin starts a small stdio MCP server (litmus) exposing:

README and each guide are also exposed as resources (litmus://README.md, litmus://01-unit-test.md, …). Everything is read from disk at call time, so editing a guide takes effect immediately — no rebuild.

Development

The MCP server lives in mcp/ (TypeScript). Because Claude Code clones plugins without running npm install, the server ships as a single self-contained bundle at mcp/bundle/litmus-mcp.mjs, which must be committed.

cd mcp
npm install
npm run smoke      # parser checks against the real guides
npm run bundle     # rebuild mcp/bundle/litmus-mcp.mjs (commit the result)
node test-handshake.mjs   # spawn the bundle and exercise the MCP protocol

Hooks, guides, and the skill are plain files — no build step; edit and commit. The version lives only in .claude-plugin/plugin.json; the MCP server reads it from there at runtime, so it can never drift.

State & privacy

• Volatile per-session change markers live in your OS temp dir and are cleaned after 24h.

• Persistent config / onboarding / cadence state live in ~/.claude/litmus (or $LITMUS_DATA), outside the plugin cache so they survive updates.

• No network calls. No usage tracking. Nothing leaves your machine.

License

MIT © retemper