Forem: Mike Lane

Your Mutation Testing Tool Should Make You Explain Yourself

Mike Lane — Tue, 17 Mar 2026 21:26:22 +0000

Every team that adopts mutation testing hits the same wall around week two.

The tool generates a mutation. Something like flipping a > to >= in a boundary check you know is dead code. Or injecting a fault into a logging call that doesn't affect behavior. The mutation survives, your score drops, and someone on the team asks the reasonable question: can we just ignore this one?

That's not the wrong question. Some mutations genuinely aren't worth killing. The wrong answer is making suppression easy and invisible.

I've been building pytest-gremlins, a mutation testing plugin for pytest, and this week we shipped v1.5.0 with a feature I've been thinking about for a while: inline mutation pardoning with mandatory reasoning and enforcement ceilings.

It works like this. You add a comment to the line:

logger.debug(f"Processing {item.id}")  # gremlin: pardon[logging-only, no behavioral impact]

The pardon keyword tells pytest-gremlins to skip mutations on that line. The brackets force you to write a reason. Not "skip" or "ignore" or "TODO." An actual explanation of why this mutation isn't worth your time.

That alone would be fine but incomplete. The ceiling is what makes it honest. You set --max-pardons=15 or --gremlin-max-pardons-pct=5 in your pyproject.toml, and pytest-gremlins enforces it. Exceed the limit and your suite fails. It's a ratchet. You can use pardons, but you can't use them to quietly erode your mutation score back to meaninglessness.

This matters because mutation testing adoption fails when teams feel like they're fighting the tool instead of improving their tests. A blanket "fix every surviving mutation" policy burns people out. A blanket "ignore what you want" policy makes the tool decorative. The pardon system sits in the middle: acknowledge the exception, explain it, and keep the total bounded.

The same release also shipped two-phase xdist integration. If you use pytest -n auto for parallel testing, pytest-gremlins now works alongside it without you changing anything. The architecture runs your normal test suite in parallel first (using xdist as usual), then runs the mutation phase sequentially. Previous mutation testing tools either couldn't coexist with xdist at all or required you to choose between parallel tests and mutation analysis.

Getting started takes about thirty seconds:

pip install pytest-gremlins
pytest --gremlins

Configure it in pyproject.toml if you want to tune things:

[tool.pytest-gremlins]
workers = 4
cache = true
report = "json,html"
max_pardons = 15

The HTML reports now include trend charts so you can see your mutation score over time, which matters more than any single run's number. And as of v1.5.1 (shipped the next day), you can generate JSON and HTML reports in the same run for both human review and CI pipeline consumption.

We also updated the comparison page this week after getting feedback from the mutmut maintainer about architecture claims we'd gotten wrong. I'd rather be accurate than flattering to our own tool. The mutation testing space is small enough that good faith matters.

If you're using pytest and you've ever wondered whether your tests actually catch the bugs they're supposed to catch, give it a try. The zero-config experience is intentional. And if you hit a mutation that feels unfair, now you can pardon it, as long as you explain yourself.

GitHub: https://github.com/mikelane/pytest-gremlins
PyPI: pip install pytest-gremlins

Announcing pytest-gremlins v1.3.0

Mike Lane — Sun, 22 Feb 2026 06:21:46 +0000

Mutation Testing That Actually Fits Into Your Workflow

Mutation testing tools (mutmut, Cosmic Ray, MutPy) exist, but most teams don't use them in practice. The bottleneck is runtime: waiting 20 minutes per mutation run makes the feedback loop too long to fit inside a normal TDD cycle.

pytest-gremlins v1.3.0 ships today with UX fixes and correctness patches that were blocking production workflows.

What Is pytest-gremlins?

pytest-gremlins is a mutation testing plugin for pytest. It injects small code modifications into your source (flipping > to >=, changing and to or, negating return values), then runs your tests to see which mutations survive. Survivors indicate code that is covered but not validated: the tests execute it, but no assertion distinguishes the mutated behavior from the original.

Four mechanisms drive its speed:

Mutation switching: instrument the code once with all mutations embedded, then toggle active mutations via environment variable. No file rewrites, no module reloads between runs.
Coverage-guided test selection: only run the tests that cover the mutated line, reducing test executions by 10-100x per mutation.
Incremental caching: skip re-testing mutations on unchanged code. Cached results are keyed by content hash.
Parallel execution: distribute mutation subprocesses across CPU cores. Mutation switching makes this safe because there is no shared mutable state between workers.

In parallel mode, pytest-gremlins is 3.73x faster than mutmut. With the cache warm on a second run, that rises to 13.82x faster. It also finds more mutations: 117 vs. mutmut's 86, with a 98% kill rate vs. 86%.

Getting Started

pip install pytest-gremlins

# Run mutation testing on your project
pytest --gremlins

# Parallel execution (recommended for speed)
pytest --gremlins --gremlin-parallel

# With coverage report alongside
pytest --gremlins --gremlin-parallel --cov

pytest-gremlins auto-discovers your source paths from pyproject.toml setuptools metadata, falling back to src/ if metadata is absent. No config file required for the common case.

What's New in v1.3.0

`--gremlin-workers` Now Implies Parallel Mode

In v1.2.x, enabling parallel execution required two flags:

pytest --gremlins --gremlin-parallel --gremlin-workers=4

In v1.3.0, specifying a worker count enables parallel mode implicitly:

pytest --gremlins --gremlin-workers=4
pytest --gremlins --gremlin-parallel  # use all CPU cores

The --gremlin-parallel flag remains valid as an explicit opt-in when you want all cores without pinning a count.

`--gremlins --cov` Actually Works Now

Combining pytest-gremlins with pytest-cov previously corrupted the .coverage data file. The mutation pre-scan subprocess wrote to .coverage without isolation, overwriting or merging data from the main test run. The coverage report was either wrong or missing.

# v1.3.0: mutation results and accurate coverage report together
pytest --gremlins --gremlin-parallel --cov --cov-report=html

The pre-scan subprocess now suppresses coverage instrumentation, so the .coverage file written by the main run is not clobbered.

Clear Error When Combining with pytest-xdist

Before v1.3.0, running pytest --gremlins -n auto produced zero mutations tested and zero output, with no indication of the conflict.

v1.3.0 fails immediately with a diagnostic:

ERROR: --gremlins and -n (pytest-xdist) cannot be combined.
Use --gremlin-workers for parallel mutation execution.

The two flags solve different problems and cannot operate simultaneously. -n parallelizes test collection and execution by distributing them across worker processes that share a single pytest session. --gremlin-workers launches isolated mutation subprocesses, each running a complete pytest session with a single mutation active. Running both at once breaks the subprocess isolation that mutation switching depends on.

Windows Path Fix

A path separator bug in WorkerPool's sources.json caused worker failures on Windows. The fix is in place and cross-platform support is now covered by CI.

Subprocess Isolation

Mutation subprocesses now suppress addopts and coverage instrumentation inherited from the host environment. Previously, host pytest configuration could leak into mutation subprocess runs, producing incorrect results on projects with complex addopts entries.

Typical Output

================== pytest-gremlins mutation report ==================

Zapped: 142 gremlins (85%)     <- tests caught the mutation
Survived: 18 gremlins (11%)    <- test gaps to investigate
Timeout: 5 gremlins (3%)
Error: 2 gremlins (1%)

Mutation score: 85%
Coverage: 94% of lines covered

========================== 167 gremlins ==========================

pyproject.toml Configuration

[tool.pytest-gremlins]
paths = ["src"]                # directories to mutate
exclude = ["**/migrations/*"]  # exclude patterns
operators = ["comparison", "boolean", "arithmetic"]  # which mutations to run

Performance Numbers

Benchmarked against mutmut (Python 3.12):

Mode	Time	vs mutmut
`--gremlins` (sequential)	17.79s	0.84x
`--gremlins --gremlin-parallel`	3.99s	3.73x faster
`--gremlins --gremlin-parallel --gremlin-cache`	1.08s	13.82x faster

Sequential mode runs slightly slower than mutmut because of subprocess isolation overhead per mutation. The tradeoff is correctness and mutation coverage: 117 mutations found vs. mutmut's 86, with a 98% kill rate vs. 86%.

Replacing 800 Lines of AI Agent Instructions with 10-Token Questions

Mike Lane — Fri, 06 Feb 2026 02:22:19 +0000

Update (2026-02-07): The original version of this article contained a significant error about how hook output reaches the agent. I ran controlled experiments and discovered:

What was wrong: I claimed that "a hook that exits 0 with text on stdout prints a message to the agent." It does not. Plain stdout from PreToolUse and PostToolUse hooks goes to the terminal's verbose mode (Ctrl+O) only. The agent never sees it. My "10-token questions" were showing up in my terminal, not in the LLM's context window. Every code example in the original article used plain echo statements that the agent silently ignored.

What actually works: Hooks must output structured JSON with an additionalContext field. This does get injected into the agent's context as a system reminder, for both root agents and subagents. The architecture, philosophy, and question-at-the-decision-boundary approach described below all hold. Only the output format was wrong.

What was always correct: Exit 2 hard-blocks work exactly as described (stderr is fed to the agent). The detection logic, the bracketing concept, and the question-vs-command design philosophy are all sound.

The code examples below have been corrected.

The Problem

"A problem is a difference between things as desired and things as perceived."
-- Gause & Weinberg

My CLAUDE.md file is 800+ lines of rules. It specifies explicit file staging, mandatory TDD, worktree isolation, GPG signing, and dozens of other constraints. Claude Code reads every line at session start, but by the third or fourth commit, the agent often runs git add -A anyway.

The instructions exist in the context window, but they arrived at position zero. By the time the agent reaches the decision to stage files, the relevant rule is buried under thousands of tokens of conversation history, code output, and tool results. The desired behavior (stage specific files) and the perceived behavior (git add -A is fine) diverge because the instruction and the decision are separated by positional distance in the context. The agent has the knowledge but lacks the prompt at the moment the decision happens.

"Are Your Lights On?"

Gause and Weinberg's Are Your Lights On? (1982) is a book about problem definition. The title comes from a story: a mountain tunnel in the Swiss Alps had a recurring problem with drivers leaving their headlights on after exiting, draining batteries while they hiked. Engineers proposed sensors, conditional instructions, automated shutoff systems. The solution that worked was a sign at the tunnel exit: "Are your lights on?"

The driver already knew how headlights work. The sign delivered a question at the decision boundary, the tunnel exit, where the driver could still act on the answer. My agent already knows the rules; what it needs is the right question at the moment it is deciding.

The Mechanism

"Don't solve other people's problems when they can solve them perfectly well themselves."
-- Gause & Weinberg

Claude Code hooks are shell scripts that fire at two lifecycle points: PreToolUse (before a tool executes) and PostToolUse (after). Each hook receives JSON on stdin containing the tool input and, for PostToolUse, the tool response. A hook that exits 0 with JSON containing an additionalContext field injects that text into the agent's context window. Plain text on stdout only appears in verbose mode (Ctrl+O in the terminal) and is invisible to the LLM. A hook that exits 2 hard-blocks the tool call and sends its stderr as the error message. The distinction matters: if your hook just echos a question, the agent will never see it.

The design choice worth examining is framing hooks as questions rather than commands. "Is there a failing test?" works where "You must write a failing test before writing production code" does not, because the question forces the agent to evaluate its current state against the standard at the moment of the decision. The command gets acknowledged when the context loads and loses salience by decision time.

Registration lives in .claude/settings.json. Here is the relevant structure for code-editing hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/lights-on-code.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/lights-on-code-post.sh"
          }
        ]
      }
    ]
  }
}

The matcher field determines which tool triggers the hook. The same script can be registered for multiple matchers (I use lights-on-code.sh for both Edit and Write). The hook runs in a subprocess with no access to the agent's state, only the JSON payload on stdin.

TDD Discipline: Bracketing the Decision

"What is the problem?"
-- Gause & Weinberg (asked repeatedly, at different stages)

The agent's most common TDD violation is writing production code before writing a failing test. Two hooks bracket the edit decision: one fires before the agent writes code, one fires after.

lights-on-code.sh (PreToolUse for Edit and Write):

#!/bin/bash
# "Are Your Lights On?" — PreToolUse:Edit/Write
# TDD enforcement: When writing production code, is there a failing test?
# Outputs JSON additionalContext so the agent actually sees the question.
# Always exits 0 (non-blocking, allows the tool to proceed).

set -euo pipefail

TOOL_INPUT=$(cat 2>/dev/null) || true
[[ -z "$TOOL_INPUT" ]] && exit 0

FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || true
[[ -z "$FILE_PATH" ]] && exit 0

FILENAME=$(basename "$FILE_PATH")
EXTENSION="${FILENAME##*.}"

# --- Only care about code files ---
case "$EXTENSION" in
    py|ts|tsx|js|jsx|go|rs|kt|java|rb|swift|c|cpp|h) ;;
    *) exit 0 ;;  # Not a code file — skip
esac

# --- Is this a test file? If so, great — that's the right thing to write first ---
if echo "$FILENAME" | grep -qiE '^test_|_test\.|\.test\.|\.spec\.|_spec\.|Test\.|Tests\.|_tests\.'; then
    exit 0
fi

# Also check if the path contains a test directory
if echo "$FILE_PATH" | grep -qiE '/tests?/|/spec/|/__tests__/|/test_'; then
    exit 0
fi

# --- This is production code. Ask the TDD question via additionalContext. ---
jq -n '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "allow",
    additionalContext: "Is there a failing test for this change? (TDD: write the test first, watch it fail, then make it pass)"
  }
}'

exit 0

lights-on-code-post.sh (PostToolUse for Edit and Write):

#!/bin/bash
# "Are Your Lights On?" — PostToolUse:Edit/Write
# TDD discipline checks AFTER code has been written.
# Different questions for production code vs test code.
# Outputs JSON additionalContext so the agent actually sees the question.
# Always exits 0 (non-blocking).

set -euo pipefail

TOOL_INPUT=$(cat 2>/dev/null) || true
[[ -z "$TOOL_INPUT" ]] && exit 0

FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || true
[[ -z "$FILE_PATH" ]] && exit 0

FILENAME=$(basename "$FILE_PATH")
EXTENSION="${FILENAME##*.}"

# --- Only care about code files ---
case "$EXTENSION" in
    py|ts|tsx|js|jsx|go|rs|kt|java|rb|swift|c|cpp|h) ;;
    *) exit 0 ;;  # Not a code file — skip
esac

# --- Is this a test file? ---
IS_TEST=false
if echo "$FILENAME" | grep -qiE '^test_|_test\.|\.test\.|\.spec\.|_spec\.|Test\.|Tests\.|_tests\.'; then
    IS_TEST=true
fi
if echo "$FILE_PATH" | grep -qiE '/tests?/|/spec/|/__tests__/|/test_'; then
    IS_TEST=true
fi

if [[ "$IS_TEST" == "true" ]]; then
    QUESTION="Did you write more test code than is sufficient to fail? (Uncle Bob's Rule #2: write only enough test to get a failure — including compilation failures.) Do you need test triangulation? (If a behavior could be faked with a hardcoded return, add another example that forces the real implementation.)"
else
    QUESTION="Did you write more production code than is sufficient to pass the one failing test? (Uncle Bob's Rule #3: minimal code to make the test green.) Does this code violate the Dependency Inversion Principle? (High-level modules should not import concrete implementations — depend on abstractions.)"
fi

jq -n --arg q "$QUESTION" '{
  hookSpecificOutput: {
    hookEventName: "PostToolUse",
    additionalContext: $q
  }
}'

exit 0

The Pre and Post hooks bracket the decision with different questions. Before writing, the question concerns prerequisites: does a failing test exist? After writing, the question concerns scope: did you write more than necessary? Weinberg's "What is the problem?" applies at both boundaries, but the specific form changes because the agent's context has changed. Before the edit, the problem is whether the agent is starting from the right place; after the edit, the problem is whether it stayed within bounds.

Error Recovery: Three Questions for Three Assumptions

"If you can't think of at least three things that might be wrong with your understanding of the problem, you don't understand the problem."
-- Gause & Weinberg

When a Bash command fails, the agent's default behavior is to retry the same command with minor variations. The lights-on-post.sh hook intercepts this pattern with three targeted questions:

# --- After ANY Bash command: check for failure (skip test commands — those fail on purpose during TDD RED) ---
TOOL_RESPONSE=$(echo "$TOOL_INPUT" | jq -r '.tool_response // empty' 2>/dev/null) || true
if [[ -n "$TOOL_RESPONSE" ]]; then
    # Skip test commands — failures are expected during RED phase
    IS_TEST_CMD=false
    if echo "$COMMAND" | grep -qE '(cargo\s+test|pytest|pnpm\s+test|npm\s+test|npx\s+jest|go\s+test|gradle.*\s+test|\.\/gradlew.*\s+test)'; then
        IS_TEST_CMD=true
    fi

    if [[ "$IS_TEST_CMD" == "false" ]]; then
        if echo "$TOOL_RESPONSE" | grep -qiE 'error:|fatal:|command not found|no such file|permission denied|ENOENT|EACCES|panic:|traceback|ModuleNotFoundError|ImportError'; then
            jq -n '{
              hookSpecificOutput: {
                hookEventName: "PostToolUse",
                additionalContext: "The command appears to have failed. Before retrying the same approach: (1) Is there a dedicated tool (Read, Grep, Glob, Edit) that handles this? (2) Did you read the error message carefully? (3) Is the approach itself wrong?"
              }
            }'
        fi
    fi
fi

Each of the three questions challenges a different assumption. Question 1: the agent may be using the wrong tool, since Claude Code has dedicated tools for file operations that are more reliable than shell equivalents. Question 2: the agent may have skipped information already present in the error output. Question 3: the entire approach may be flawed, not just the execution.

The hook excludes test commands because test failures during TDD's RED phase are the desired state. Without this exclusion, every intentional test failure would generate a warning, which would train the agent to ignore the hook's output entirely.

When Questions Are Not Enough

"Each solution is the source of the next problem."
-- Gause & Weinberg

Some agent behaviors are not correctable by questions because the consequences are irreversible. Force-pushing to main overwrites remote history. Bypassing GPG signing breaks the chain of trust. Disabling git hooks with --no-verify defeats the verification system entirely. For these cases, block-dangerous-commands.sh uses exit 2 to hard-block the tool call:

block_with_reason() {
    local reason="$1"
    echo "BLOCKED: $reason" >&2
    exit 2
}

# Force pushes to main/master
if echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force|git\s+push\s+-f'; then
    if echo "$COMMAND" | grep -qE '\s(main|master)\b'; then
        block_with_reason "Force push to main/master is forbidden"
    fi
fi

# Prevent skipping git hooks
if echo "$COMMAND" | grep -qE 'git\s+commit.*--no-verify|git\s+push.*--no-verify'; then
    block_with_reason "Skipping git hooks (--no-verify) is not allowed"
fi

# Prevent bypassing hooks via environment variables
if echo "$COMMAND" | grep -qE 'LEFTHOOK=0|HUSKY=0'; then
    block_with_reason "Bypassing git hooks via environment variables is not allowed. Fix the issue instead of disabling the hook."
fi

The design boundary between soft nudge (exit 0) and hard block (exit 2) is reversibility. If the agent stages all files instead of specific ones, I can unstage them; if the agent force-pushes to main, the remote history is rewritten and recovery requires coordination with every collaborator. Using hard blocks for every hook would be counterproductive: the agent would spend its token budget searching for workarounds instead of doing the work.

The Full System

"Whose problem is it?"
-- Gause & Weinberg

Twelve scripts cover the decision boundaries I care about:

Hook	Trigger	What It Asks
`block-dangerous-commands.sh`	PreToolUse:Bash	Hard-blocks force-push, --no-verify, rm -rf /
`lights-on.sh`	PreToolUse:Bash	"Are you staging specific files?", "Are you on the right branch?"
`lights-on-code.sh`	PreToolUse:Edit/Write	"Is there a failing test for this change?"
`lights-on-task.sh`	PreToolUse:Task	"Is this agent working in a worktree?", "Did you create tasks?"
`lights-on-github-pre.sh`	PreToolUse:mcp_github	"Did you run quality checks before this PR?"
`lights-on-post.sh`	PostToolUse:Bash	"Did you install deps?", "Is the approach itself wrong?"
`lights-on-code-post.sh`	PostToolUse:Edit/Write	"Did you write more code than sufficient to pass?"
`lights-on-prose-post.sh`	PostToolUse:Edit/Write	"Did you use em-dashes or AI slop?"
`lights-on-read-edit-post.sh`	PostToolUse:Read/Edit	"Did you use Glob to verify the path?"
`lights-on-task-post.sh`	PostToolUse:Task	"Did you verify the agent's work?"
`lights-on-github.sh`	PostToolUse:mcp_github	"Add to project board? Link as sub-issue?"
`notify-git-failures.sh`	PostToolUse:Bash	(Slack notification on git failure)

The system introduces overhead. Each question that fires adds 10-15 tokens to the context window. The tradeoff is those tokens versus the cost of the agent going down a wrong path for 50+ tool calls before I notice. In practice, most hooks exit silently for non-matching commands (an ls command does not trigger the git staging question), so the per-operation cost concentrates on the decisions where drift is most likely.

The prose hook (lights-on-prose-post.sh) illustrates Weinberg's point that every intervention has second-order effects: it occasionally flags legitimate uses of dashes in code comments. The question is whether the cost of false positives is lower than the cost of the original failure mode (AI-generated prose full of em-dashes). For my use case, it is.

Build Your Own

"Not all problems require solutions. But all solutions require a problem."
-- Gause & Weinberg

Three steps to build hooks for your own workflow:

Identify your top 3 agent failure modes. Check your git history for commits you had to fix, and check your conversation logs for repeated corrections. The failures you correct most often are the ones worth hooking.

Determine the decision boundary. If the failure is preventable (the agent should not have taken the action), use PreToolUse. If the failure is correctable (the action happened, but the follow-up was wrong), use PostToolUse. Most failures are correctable, which is why most of my hooks are PostToolUse.

Write a question, not a command. A question makes the problem the agent's to solve; a command makes enforcement your problem, and the agent will comply at context-load time and drift later. Here is a minimal PreToolUse template:

#!/bin/bash
set -euo pipefail
TOOL_INPUT=$(cat 2>/dev/null) || true
[[ -z "$TOOL_INPUT" ]] && exit 0

COMMAND=$(echo "$TOOL_INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) || true

if echo "$COMMAND" | grep -qE 'YOUR_PATTERN'; then
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "allow",
        additionalContext: "Your question here?"
      }
    }'
fi

exit 0

For PostToolUse hooks, the JSON is slightly different (no permissionDecision, since the tool already ran):

    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PostToolUse",
        additionalContext: "Your question here?"
      }
    }'

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/your-hook.sh" }]
      }
    ]
  }
}

The Sign at the Exit

Twelve scripts totaling roughly 500 lines of shell reinforce 800+ lines of CLAUDE.md instructions by delivering the relevant subset at the moment the agent is making the decision those instructions address. The mechanism is a shell script that reads JSON and returns JSON: a structured additionalContext field that gets injected into the agent's context window at the decision boundary. Plain stdout goes to your terminal; additionalContext goes to the agent. The distinction between the two output channels is the difference between a sign you can see and a sign the driver can see.

Gause and Weinberg figured out in 1982 that the driver does not need a lecture on electrical systems; the driver needs six words on a sign at the tunnel exit. The same principle applies to AI agents, and the implementation is a shell script that reads JSON and returns JSON. Start with your agent's most frequent failure mode, find the decision boundary where it occurs, and write a question that fits there.

Your Tests Pass. But Would They Catch This Bug?

Mike Lane — Wed, 28 Jan 2026 00:38:24 +0000

You have 90% code coverage, green CI, and you ship. A user reports that >= should have been >. Your tests executed that line but never verified the boundary mattered.

Code coverage counts executed lines. Mutation testing injects small bugs and checks whether your tests detect them. If tests still pass after changing >= to >, you found a gap.

Why Mutation Testing Has Been Impractical

Traditional tools (mutmut, cosmic-ray) rewrite source files, reload modules, and run the full test suite per mutation. A codebase with 100 mutations and a 10-second test suite takes 17+ minutes. That runtime kills feedback loops.

pytest-gremlins Architecture

pytest-gremlins achieves 13.8x speedup through three mechanisms:

Mutation Switching: All mutations are embedded during a single instrumentation pass. Switching between mutations requires only an environment variable change, eliminating per-mutation file I/O and module reloads.

Coverage-Guided Test Selection: The plugin tracks which tests cover each line. When testing a mutation on line 42, it runs only the 3 tests that touch line 42 instead of all 200 tests.

Incremental Caching: Results are keyed by content hash of source and test files. Unchanged code skips mutation testing entirely on subsequent runs.

Benchmark: pytest-gremlins vs mutmut

Measured on Python 3.12 in Docker:

Configuration	Time	vs. mutmut
mutmut	14.90s	baseline
pytest-gremlins (sequential)	17.79s	0.84x
pytest-gremlins (parallel)	3.99s	3.7x faster
pytest-gremlins (parallel + cache)	1.08s	13.8x faster

Sequential mode is slower because pytest-gremlins runs additional mutation operators. Parallel mode, safe due to mutation switching (no shared mutable state), delivers the speedup. Cached runs approach instant for unchanged code.

Installation and Usage

pip install pytest-gremlins
pytest --gremlins --gremlin-parallel --gremlin-cache

Output identifies specific gaps:

================== pytest-gremlins mutation report ==================

Zapped: 142 gremlins (89%)
Survived: 18 gremlins (11%)

Top surviving gremlins:
  src/auth.py:42    >= → >     (boundary not tested)
  src/utils.py:17   + → -      (arithmetic not verified)
  src/api.py:88     True → False (return value unchecked)
=====================================================================

Each survivor is a line number, the mutation applied, and the gap it reveals. Line 42 has a boundary condition no test verifies.

Configuration

Add to pyproject.toml:

[tool.pytest-gremlins]
operators = ["comparison", "arithmetic", "boolean"]
paths = ["src"]
exclude = ["**/migrations/*"]
min_score = 80

Target specific files with --gremlin-targets=src/auth.py.

Try It On Your Code

Run this on your highest-coverage module:

pip install pytest-gremlins
pytest --gremlins --gremlin-parallel --gremlin-targets=src/your_critical_module.py

Survivors show exactly where your tests verify execution but not correctness. Fix one, run again in under 2 seconds with caching.

Links: PyPI | GitHub | Docs

Dioxide v2.0.0: Clean Architecture Made Simple

Mike Lane — Sat, 24 Jan 2026 01:51:54 +0000

TL;DR: Dioxide is a dependency injection framework for Python that makes hexagonal architecture the path of least resistance. v2.0.0 adds constructor-based profile scanning, extensible custom profiles, and introspection APIs.

What is Dioxide?

Dioxide's decorators encode hexagonal architecture patterns directly into your code. @adapter.for_(Port, profile=...) forces you to declare which abstraction you're implementing and when it applies. @service marks core domain logic that depends on ports, not concrete implementations. The result: clean architecture becomes the easiest path forward.

from dioxide import Container, adapter, service, Profile
from typing import Protocol

# Define your port (interface)
class EmailPort(Protocol):
    async def send(self, to: str, body: str) -> None: ...

# Production adapter - real infrastructure
@adapter.for_(EmailPort, profile=Profile.PRODUCTION)
class SendGridAdapter:
    async def send(self, to: str, body: str) -> None:
        # Real SendGrid API call
        ...

# Test adapter - fast fake
@adapter.for_(EmailPort, profile=Profile.TEST)
class FakeEmailAdapter:
    sent: list[dict] = []
    async def send(self, to: str, body: str) -> None:
        self.sent.append({"to": to, "body": body})

# Service depends on the PORT, not the concrete adapter
@service
class NotificationService:
    def __init__(self, email: EmailPort):
        self.email = email

# Production: uses SendGrid
async with Container(profile=Profile.PRODUCTION) as container:
    svc = container.resolve(NotificationService)

# Tests: uses fast fake, no network calls
async with Container(profile=Profile.TEST) as container:
    svc = container.resolve(NotificationService)

What's New in v2.0.0

Auto-Scan via Constructor

Pass profile directly to the Container constructor. The container scans for registered components automatically:

# v2.0: profile in constructor triggers auto-scan
container = Container(profile=Profile.PRODUCTION)

# v1.x: explicit scan still works
container = Container()
container.scan(profile=Profile.PRODUCTION)

Extensible Custom Profiles

Profile changed from StrEnum to an extensible str subclass. Create domain-specific profiles that work identically to built-ins:

LOAD_TEST = Profile("load-test")
INTEGRATION = Profile("integration")

@adapter.for_(DatabasePort, profile=INTEGRATION)
class IntegrationDatabaseAdapter:
    ...

Container Introspection

Debug container state with list_registered():

container = Container(profile=Profile.TEST)
for registered_type in container.list_registered():
    print(f"Registered: {registered_type.__name__}")

Pytest Fixtures

The dioxide.testing module provides isolation helpers:

from dioxide.testing import fresh_container

async def test_my_service():
    async with fresh_container(profile=Profile.TEST) as container:
        service = container.resolve(MyService)
        # Container is fresh, isolated, and auto-cleaned

Breaking Changes

If you used Profile's StrEnum methods, update your code:

Old (v1.x)	New (v2.0)
`profile.value`	`str(profile)`
`profile.name`	Use constant directly
`for p in Profile:`	Explicit list

Why Dioxide?

Type-safe: Full mypy support catches type mismatches in constructor injection at lint time
Fast: Rust-backed container with sub-microsecond cached singleton lookup
Framework integrations: FastAPI, Flask, Django, Celery, Click
Testing-oriented: Profile system enables fast in-memory fakes instead of mocks

Get Started

pip install dioxide

Documentation | GitHub

dioxide v1.1.2: Multi-Binding for Plugin Systems

Mike Lane — Wed, 21 Jan 2026 05:46:22 +0000

dioxide v1.1.2 adds multi-binding support. The multi=True parameter on @adapter.for_() registers multiple adapters for the same port, and list[Port] type hints collect them at resolution time.

from dioxide import adapter, service, Container, Profile

@adapter.for_(PluginPort, multi=True, priority=10)
class ValidationPlugin:
    def process(self, data: str) -> str:
        return validate(data)

@adapter.for_(PluginPort, multi=True, priority=20)
class TransformPlugin:
    def process(self, data: str) -> str:
        return data.upper()

@service
class DataProcessor:
    def __init__(self, plugins: list[PluginPort]) -> None:
        self.plugins = plugins  # Both plugins, ordered by priority

The container resolves list[PluginPort] to a list containing all registered multi-binding adapters for the active profile, sorted by priority (lower values first).

Plugin Systems

Mutation testing frameworks need to collect all mutation operators. With multi-binding, each operator is a decorated class that the container discovers during scanning:

class MutationOperator(Protocol):
    def can_mutate(self, node: AST) -> bool: ...
    def mutate(self, node: AST) -> list[AST]: ...

@adapter.for_(MutationOperator, multi=True)
class ArithmeticOperator:
    def can_mutate(self, node: AST) -> bool:
        return isinstance(node, ast.BinOp)

    def mutate(self, node: AST) -> list[AST]:
        # Replace + with -, * with /, etc.
        ...

@adapter.for_(MutationOperator, multi=True)
class ComparisonOperator:
    def can_mutate(self, node: AST) -> bool:
        return isinstance(node, ast.Compare)

    def mutate(self, node: AST) -> list[AST]:
        # Replace == with !=, < with >=, etc.
        ...

@service
class MutationEngine:
    def __init__(self, operators: list[MutationOperator]) -> None:
        self.operators = operators

    def mutate_node(self, node: AST) -> list[AST]:
        for op in self.operators:
            if op.can_mutate(node):
                return op.mutate(node)
        return []

To add an operator, create a class decorated with @adapter.for_(MutationOperator, multi=True) in a module that the container scans.

Ordered Processing Pipelines

The priority parameter controls injection order. Lower values come first, negative values run before the default of 0:

class PipelineStep(Protocol):
    async def execute(self, context: dict) -> dict: ...

@adapter.for_(PipelineStep, multi=True, priority=-10)
class AuthenticationStep:
    async def execute(self, context: dict) -> dict:
        context["user"] = await authenticate(context["token"])
        return context

@adapter.for_(PipelineStep, multi=True, priority=0)
class ValidationStep:
    async def execute(self, context: dict) -> dict:
        validate_request(context)
        return context

@adapter.for_(PipelineStep, multi=True, priority=100)
class AuditStep:
    async def execute(self, context: dict) -> dict:
        await log_request(context)
        return context

@service
class RequestPipeline:
    def __init__(self, steps: list[PipelineStep]) -> None:
        self.steps = steps  # Ordered: Auth -> Validation -> Audit

    async def run(self, context: dict) -> dict:
        for step in self.steps:
            context = await step.execute(context)
        return context

Profile-Filtered Collections

Multi-bindings respect the profile system. Only adapters matching the active profile are included in the resolved list:

@adapter.for_(NotificationChannel, multi=True, profile=Profile.PRODUCTION)
class EmailChannel:
    async def notify(self, message: str) -> None:
        await send_email(message)

@adapter.for_(NotificationChannel, multi=True, profile=Profile.PRODUCTION)
class SlackChannel:
    async def notify(self, message: str) -> None:
        await post_to_slack(message)

@adapter.for_(NotificationChannel, multi=True, profile=Profile.TEST)
class FakeChannel:
    def __init__(self):
        self.messages = []

    async def notify(self, message: str) -> None:
        self.messages.append(message)

@service
class NotificationDispatcher:
    def __init__(self, channels: list[NotificationChannel]) -> None:
        self.channels = channels

    async def broadcast(self, message: str) -> None:
        for channel in self.channels:
            await channel.notify(message)

With Profile.PRODUCTION, channels contains [EmailChannel, SlackChannel]. With Profile.TEST, it contains [FakeChannel].

Constraints and Behavior

A port must be either single-binding or multi-binding across all profiles. Mixing multi=True and multi=False adapters for the same port raises an error at scan() time:

# This fails at scan() time:
@adapter.for_(SomePort, profile=Profile.PRODUCTION)  # single
class SingleAdapter: ...

@adapter.for_(SomePort, multi=True, profile=Profile.TEST)  # multi
class MultiAdapter: ...

If no multi-binding adapters are registered for a port, list[Port] resolves to an empty list rather than raising an error. This supports plugin architectures where zero implementations is valid.

The type hint must be exactly list[Port]. Other generic types like Sequence[Port] or Iterable[Port] are not supported.

Building Guardrails for AI Coding Assistants: A PreToolUse Hook System for Claude Code

Mike Lane — Sun, 18 Jan 2026 22:09:55 +0000

AI coding assistants implement code quickly but follow their training defaults, not your project rules. They do not know your team bans git reset --hard, requires GPG-signed commits, or uses a different GitHub org than your username.

Claude Code's PreToolUse hook system intercepts tool calls before execution, blocks dangerous operations, and injects contextual guidance. This article walks through a production implementation consisting of four specialized hooks.

Version Note: The additionalContext feature used in this article requires Claude Code v2.1.9 or later (released January 16, 2026). Earlier versions supported blocking hooks but not context injection. This capability originated from feature request #15345.

The Hook Contract

A PreToolUse hook is an executable that receives JSON on stdin and communicates via exit codes and stdout/stderr:

# Input (stdin)
{
  "tool_name": "Bash",
  "tool_input": {"command": "git reset --hard HEAD~3"}
}

# Exit code 0: Allow (stdout parsed for additionalContext)
# Exit code 2: Block (stderr displayed to user)

The hook output format for allowing with context injection:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "additionalContext": "Your reminder or context here"
  }
}

Hook 1: Safety Guards

The first hook blocks destructive operations before they execute.

BLOCKING_RULES: list[SafetyRule] = [
    SafetyRule(
        pattern=r"git\s+reset\s+--hard",
        action="block",
        message="BLOCKED: Use `git stash` or `git rebase` instead. "
        "`git reset --hard` destroys uncommitted work.",
    ),
    SafetyRule(
        pattern=r"--no-gpg-sign",
        action="block",
        message="BLOCKED: GPG signing is mandatory. Fix GPG issues, don't bypass.",
    ),
    SafetyRule(
        pattern=r"git\s+(?:add\s+)?(?:-A|--all|\.\s*$)",
        action="block",
        message="BLOCKED: Explicitly stage files to avoid committing unwanted files.",
    ),
]

When asked to commit changes, Claude often runs git add -A to stage everything. In repositories with build artifacts or .env files, this stages files that should never be committed. Forcing explicit staging ensures intentional commits.

Warning rules follow the same pattern but allow the operation while injecting context:

WARNING_RULES: list[SafetyRule] = [
    SafetyRule(
        pattern=r"git\s+push\s+--force(?!\s*-with-lease)",
        action="warn",
        message="WARNING: Use `--force-with-lease` for safer force push.",
    ),
    SafetyRule(
        pattern=r"\.env",
        action="warn",
        message="WARNING: This file may contain secrets. Never commit .env files.",
    ),
]

The execution logic checks blocking rules first, then warnings:

def check_command(command: str) -> tuple[str, str]:
    for rule in BLOCKING_RULES:
        if rule.matches(command):
            return ("block", rule.message)

    for rule in WARNING_RULES:
        if rule.matches(command):
            return ("warn", rule.message)

    return ("allow", "")

Hook 2: Context Injection for GitHub API Calls

Repository paths do not always match GitHub organization names. My local checkout lives at ~/dev/AcmeCorp/webapp, but the GitHub owner is AcmeCorp, not my username jdoe. Without intervention, Claude defaults to the wrong owner for API calls.

The context injection hook injects repository metadata whenever Claude uses GitHub MCP tools:

GITHUB_BASE_CONTEXT = """CONTEXT: This repo's GitHub owner is 'AcmeCorp', NOT 'jdoe'.
Always use owner='AcmeCorp' in GitHub API calls.
Repository name: webapp
Default branch: main"""

PROJECT_BOARD_CONTEXT = """
Project board ID: PVT_xxxxxxxxxxxxxxxxxxxx
Epic Priority field ID: PVTF_xxxxxxxxxxxxxxxxxxxxxxx
Status field ID: PVTSSF_xxxxxxxxxxxxxxxxxxxxxxx

Note: gh project item-edit silently fails for Number fields. Use GraphQL mutations instead."""

The hook matcher uses regex to capture all GitHub MCP tools:

{
  "matcher": "mcp__github__.*",
  "hooks": [{"type": "command", "command": "python3 .../context-injection.py"}]
}

Project-related tools receive additional context about board IDs.

Hook 3: Workflow Rule Enforcement

Some workflow rules cannot be enforced by linters: TDD discipline, worktree usage, commit signing. This hook surfaces reminders at relevant moments without blocking operations:

GPG_REMINDER = WorkflowReminder(
    message="GPG REMINDER: Never use `--no-gpg-sign`. If GPG fails, check sandbox mode."
)

TDD_REMINDER = WorkflowReminder(
    message="TDD REMINDER: Is there a failing test? Write the RED test first, "
    "then write minimal code to make it GREEN."
)

WORKTREE_REMINDER = WorkflowReminder(
    message="WORKTREE REMINDER: You appear to be working directly on main. "
    "Use `git worktree add .worktrees/issue-XX-description -b issue-XX-description`"
)

Reminders are injected based on tool and file context:

def get_write_edit_reminders(file_path: str) -> list[str]:
    reminders = []

    # TDD reminder for Go production code
    if is_go_production_code(file_path):
        reminders.append(TDD_REMINDER.message)

    # Worktree reminder if editing production code outside worktree
    if not is_in_worktree() and is_production_code_path(file_path):
        reminders.append(WORKTREE_REMINDER.message)

    return reminders

The worktree check uses an environment variable to detect the current directory:

def is_in_worktree() -> bool:
    cwd = os.environ.get("PWD", os.getcwd())
    return ".worktrees/" in cwd

Hook 4: Skill Suggestion Engine

Claude Code supports "skills" (reusable instruction sets for specific domains). The skill suggestion hook maps file patterns to relevant skills, prompting Claude to load domain-specific guidance before proceeding.

SKILL_TRIGGERS: list[SkillTrigger] = [
    # Test files need test classification + TDD patterns
    SkillTrigger(
        skills=("classifying-test-sizes", "developing-with-tdd"),
        path_contains="_test.go",
    ),
    # Temporal workflows need TDD + Temporal + Go monorepo skills
    SkillTrigger(
        skills=("developing-with-tdd", "developing-with-temporal", "working-with-go-monorepo"),
        path_contains="apps/workers/",
        extension=".go",
    ),
    # Database migrations
    SkillTrigger(
        skills=("working-with-atlas-migrations",),
        path_contains="db/migrations/",
    ),
]

The trigger list uses first-match-wins ordering. Specific patterns (test files, migrations) appear before generic patterns (any Go file in apps/). This ensures a _test.go file triggers test-specific skills rather than generic Go guidance.

The output reminds Claude to invoke the relevant skills:

if skills:
    skill_list = ", ".join(f"'{s}'" for s in skills)
    output = {
        "hookSpecificOutput": {
            "additionalContext": (
                f"SKILL REMINDER: Before proceeding, invoke these skills: {skill_list}. "
                f"They contain patterns, gotchas, and best practices for this file type."
            )
        }
    }

Hook Configuration

The settings.json file orchestrates which hooks run for which tools:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [{"type": "command", "command": "python3 .../suggest-skills.py"}]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {"type": "command", "command": "python3 .../safety-guards.py"},
          {"type": "command", "command": "python3 .../workflow-rules.py"}
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "python3 .../workflow-rules.py"}]
      },
      {
        "matcher": "mcp__github__.*",
        "hooks": [{"type": "command", "command": "python3 .../context-injection.py"}]
      }
    ]
  }
}

The matcher field accepts regex patterns. Bash commands receive both safety guards and workflow rules. Write/Edit operations trigger workflow rules and skill suggestions. GitHub MCP tools receive context injection.

Observations

In my workflow, the hooks have changed how Claude interacts with the repository:

Claude no longer attempts git reset --hard. The safety hook blocks it and suggests alternatives.
GitHub API calls default to the correct owner. Before the context hook, I corrected the owner manually in roughly one of five API calls.
The TDD reminder appears on every Go file edit. I cannot quantify compliance, but the reminder makes skipping the red-test step feel deliberate rather than accidental.
Skill loading happens automatically when I edit workflow files, instead of requiring me to remember to invoke them.

Implementation Considerations

Hooks cannot modify tool inputs, only allow, block, or inject context. Complex validation requiring multiple file reads will slow down every tool call. Hooks see individual tool calls, not conversation context.

Error handling defaults to permissive: JSON parse failures result in exit code 0 (allow) rather than blocking operations. This prevents a malformed hook from breaking the development workflow entirely.

The complete implementation consists of four Python files totaling under 400 lines. Each hook has a single responsibility, making them straightforward to test and modify. Adding new concerns means adding new hooks, keeping each hook focused.

CLI Validation Patterns with Maybe Monads

Mike Lane — Fri, 09 Jan 2026 01:39:32 +0000

CLI Validation Patterns with Maybe Monads

CLI input validation typically scatters error handling across multiple try/except blocks, making the control flow difficult to follow and test. The Maybe monad offers an alternative: compose validation steps into pipelines where errors propagate automatically, and each step either succeeds with a value or fails with an error message.

This article demonstrates four patterns for CLI validation using valid8r, a Python library that implements the Maybe monad for parsing and validation.

The Problem with Nested Exception Handling

Consider validating a configuration file path. The input must pass several checks: the path must exist, be a file (not a directory), be readable, have a .json extension, and contain valid JSON with required keys.

import os
import json

def validate_config_file(path: str) -> dict:
    if not os.path.exists(path):
        raise ValueError(f"{path} does not exist")
    if not os.path.isfile(path):
        raise ValueError(f"{path} is not a file")
    if not os.access(path, os.R_OK):
        raise ValueError(f"{path} is not readable")
    if not path.endswith('.json'):
        raise ValueError(f"{path} must be .json")
    try:
        with open(path) as f:
            config = json.load(f)
    except json.JSONDecodeError as e:
        raise ValueError(f"Invalid JSON: {e}")
    required = ['database', 'api_key']
    missing = [k for k in required if k not in config]
    if missing:
        raise ValueError(f"Missing keys: {missing}")
    return config

This function works, but has structural problems. Each check is an independent if-statement, so adding or removing checks requires modifying multiple locations. The JSON parsing sits inside a nested try-except. Testing requires mocking filesystem state or creating actual files.

The Maybe monad addresses these issues by representing each validation step as a function that returns either Success(value) or Failure(error). Steps compose through bind, which passes the value to the next function if the previous succeeded, or short-circuits if it failed.

Pattern 1: Chained Validation with bind

The bind method chains validation steps. If any step fails, the remaining steps are skipped and the error propagates to the end.

from valid8r import parsers, validators
from valid8r.core.maybe import Maybe, Success, Failure

def validate_port(text: str) -> Maybe[int]:
    """Parse and validate a port number in range 1-65535."""
    return (
        parsers.parse_int(text)
        .bind(validators.minimum(1))
        .bind(validators.maximum(65535))
    )

# Usage
result = validate_port("8080")
match result:
    case Success(port):
        print(f"Starting server on port {port}")
    case Failure(error):
        print(f"Invalid port: {error}")

Each validator is a function that takes a value and returns Maybe[T]. The bind method unwraps Success, passes the value to the next function, and returns the result. If the current result is Failure, bind returns it unchanged.

For port validation:

parsers.parse_int("8080") returns Success(8080)
.bind(validators.minimum(1)) receives 8080, checks 8080 >= 1, returns Success(8080)
.bind(validators.maximum(65535)) receives 8080, checks 8080 <= 65535, returns Success(8080)

If the input is "70000":

parsers.parse_int("70000") returns Success(70000)
.bind(validators.minimum(1)) returns Success(70000)
.bind(validators.maximum(65535)) returns Failure("Value must be at most 65535")

The chain stops at the first failure. No subsequent validators execute.

Pattern 2: Combining Validators with Operators

The Validator class supports & (and), | (or), and ~ (not) operators for combining validators.

from valid8r import parsers, validators
from valid8r.core.maybe import Maybe

def validate_username(text: str) -> Maybe[str]:
    """Username: 3-20 chars, alphanumeric with underscores."""
    return parsers.parse_str(text).bind(
        validators.length(3, 20)
        & validators.matches_regex(r'^[a-zA-Z0-9_]+$')
    )

def validate_age(text: str) -> Maybe[int]:
    """Age: positive integer, max 150."""
    return parsers.parse_int(text).bind(
        validators.minimum(0) & validators.maximum(150)
    )

The & operator creates a validator that passes only if both validators pass. The | operator passes if either validator passes. The ~ operator inverts a validator.

from pathlib import Path
from valid8r import parsers, validators

def validate_output_path(text: str) -> Maybe[Path]:
    """Output path: must be a directory OR a writable file."""
    return parsers.parse_path(text, resolve=True).bind(
        validators.exists()
    ).bind(
        validators.is_dir() | (validators.is_file() & validators.is_writable())
    )

def validate_safe_upload(text: str) -> Maybe[Path]:
    """Upload: must exist, be readable, NOT be executable."""
    return parsers.parse_path(text).bind(
        validators.exists()
        & validators.is_readable()
        & ~validators.is_executable()
    )

The ~validators.is_executable() validator passes if the file is not executable. This inverts the success/failure of the wrapped validator.

Pattern 3: Filesystem Validation Pipelines

Filesystem validation often requires multiple checks in sequence: existence, type, permissions, and constraints. The Maybe pattern handles this with composable pipelines.

from pathlib import Path
from valid8r import parsers, validators
from valid8r.core.maybe import Maybe, Success, Failure

def validate_config_file(path_str: str) -> Maybe[Path]:
    """Validate configuration file: exists, readable, YAML/JSON, under 1MB."""
    return (
        parsers.parse_path(path_str, expand_user=True, resolve=True)
        .bind(validators.exists())
        .bind(validators.is_file())
        .bind(validators.is_readable())
        .bind(validators.has_extension(['.yaml', '.yml', '.json']))
        .bind(validators.max_size(1024 * 1024))
    )

def validate_upload_file(path_str: str) -> Maybe[Path]:
    """Validate uploaded file: PDF/DOCX, readable, under 10MB."""
    return (
        parsers.parse_path(path_str)
        .bind(validators.exists())
        .bind(validators.is_file())
        .bind(validators.is_readable())
        .bind(validators.has_extension(['.pdf', '.docx']))
        .bind(validators.max_size(10 * 1024 * 1024))
    )

# Usage in a CLI handler
def handle_upload(file_path: str) -> dict:
    match validate_upload_file(file_path):
        case Success(path):
            return {
                'status': 'success',
                'filename': path.name,
                'size': path.stat().st_size
            }
        case Failure(error):
            return {
                'status': 'error',
                'message': error
            }

The parse_path function supports options like expand_user=True (expands ~ to home directory) and resolve=True (converts to absolute path). These run before validation begins.

Adding or removing validation steps requires changing one line. Each step is independently testable. Error messages propagate automatically with context about which check failed.

Pattern 4: Interactive Prompts with Retry Logic

The ask function combines parsing, validation, and retry logic for interactive CLI prompts.

from valid8r import parsers, validators
from valid8r.prompt import ask

def get_user_config() -> dict:
    """Prompt user for configuration with validation and retry."""

    # Port with range validation, retry up to 3 times
    port_result = ask(
        "Enter port (1-65535): ",
        parser=parsers.parse_int,
        validator=validators.between(1, 65535),
        default=8080,
        retry=3
    )

    # Email with RFC validation, unlimited retries
    email_result = ask(
        "Enter email: ",
        parser=parsers.parse_email,
        retry=True
    )

    # Boolean with various formats accepted (yes/no, true/false, y/n, 1/0)
    debug_result = ask(
        "Enable debug mode? ",
        parser=parsers.parse_bool,
        default=False
    )

    return {
        'port': port_result.value_or(8080),
        'email': email_result.value_or(None),
        'debug': debug_result.value_or(False)
    }

The ask function handles the prompt loop:

Display prompt with default value if provided
Parse input using the parser function
Validate using the validator function (if provided)
On failure, display error and retry (if retry is True or a positive integer)
Return Maybe[T] with final result

For custom validation, compose a parser with validators using bind:

def custom_port_parser(text: str) -> Maybe[int]:
    return parsers.parse_int(text).bind(validators.between(1, 65535))

port_result = ask(
    "Enter port: ",
    parser=custom_port_parser,
    retry=True
)

Integrating with argparse

The type_from_parser adapter connects valid8r parsers to argparse:

import argparse
from valid8r import parsers, validators
from valid8r.integrations.argparse import type_from_parser
from valid8r.core.maybe import Maybe

def port_parser(text: str) -> Maybe[int]:
    return parsers.parse_int(text).bind(
        validators.minimum(1) & validators.maximum(65535)
    )

parser = argparse.ArgumentParser()
parser.add_argument(
    '--email',
    type=type_from_parser(parsers.parse_email),
    required=True,
    help='Email address'
)
parser.add_argument(
    '--port',
    type=type_from_parser(port_parser),
    default=8080,
    help='Port number (1-65535)'
)

args = parser.parse_args()
# args.email is EmailAddress(local='user', domain='example.com')
# args.port is int

When validation fails, argparse displays the error message from the Failure and exits with status 2. The error message comes from the validator, not a generic type conversion error.

Tradeoffs

The Maybe monad pattern has costs:

Cognitive overhead: Developers unfamiliar with monads need to learn bind, map, Success, and Failure. The functional style differs from imperative Python.

Stack traces: When validation fails deep in a pipeline, the stack trace points to bind internals rather than the specific validator. Error messages must be descriptive since line numbers are less helpful.

Type inference: Complex chains can confuse type checkers. Explicit type annotations help.

Overkill for simple cases: A single if not value: raise ValueError() is clearer than a Maybe pipeline for trivial validation.

The pattern pays off when:

Validation requires multiple sequential steps
Error messages need to propagate unchanged
Validation logic should be testable in isolation
The same validators compose into different pipelines

Summary

The Maybe monad transforms validation from scattered conditionals into composable pipelines. Each validator is a function from T to Maybe[T], and bind chains them together. Operators (&, |, ~) combine validators logically. The ask function adds interactive prompting with retry logic.

Install with pip install valid8r. The source is at github.com/mikelane/valid8r.

Code examples tested with valid8r 1.25.0 on Python 3.12.

The Multiplier Is the Job Now: Why Agentic AI Changes Everything

Mike Lane — Fri, 26 Dec 2025 20:59:06 +0000

I spent ten minutes with Claude Code one evening this week.

Not ten minutes prompting, or tweaking, or trying to discover the right incantation. Ten minutes actually working. In that time, it produced roughly forty-eight thousand lines of code.

That number is absurd enough that it immediately invites skepticism, including my own. So I measured it. I tracked what was happening, how much time I was actually involved, and what the output looked like when translated into the units we normally use to reason about engineering work.

What unsettled me was not simply the volume of code. It was how little my own pace seemed to matter. The system continued to produce whether I typed quickly or not. My role drifted almost immediately from writing to deciding, redirecting, and occasionally stopping it from going somewhere unhelpful.

Curiosity turned into instrumentation. I built a few Grafana dashboards to see what was actually happening under the hood. Over the course of an hour, the system generated about forty-eight thousand lines of code. My direct involvement during that window totaled roughly ten minutes.

Using a very generous estimate of seventy-five production-quality lines per developer hour, that output corresponds to nearly four weeks of work. When I ran multiple agents in parallel across two repositories, the ratio climbed even higher. Briefly, it reached five figures.

I do not think lines of code are a meaningful proxy for value. I have spent enough of my career deleting them to be certain of that. But lines of code are still how organizations budget, staff, and estimate. In that context, the arithmetic becomes difficult to ignore.

A senior engineer costs something like one hundred fifty to two hundred thousand dollars a year when fully loaded. Call it a hundred dollars an hour to keep the math honest. At that rate, each line of production code costs roughly a dollar.

The cost per line I observed here was a fraction of a cent.

I am on a two-hundred-dollar-per-month plan. In one hour, the system generated over seventy dollars’ worth of equivalent API output. My share of that hour’s subscription cost was less than thirty cents. Whatever else one thinks about this setup, it is not expensive.

At this point, there is usually an objection, sometimes spoken and sometimes not. Surely you cannot be reviewing tens of thousands of lines of code. Surely quality collapses under that kind of volume.

Of course I am not reading it line by line. That would be pointless, and it would miss the more important shift that is happening here.

The responsibility for quality moves upstream.

I rely on automated tests that fail loudly and early. I track not just whether tests pass, but how well they interrogate the code: branch coverage, mutation testing, behavior-level acceptance criteria written before implementation begins. I use specialized agents that critique one another’s output. Guardrails prevent dangerous operations before they happen. When something breaks, I see it immediately.

What I spend my time on looks very different than it used to. I define constraints. I clarify intent. I decide what matters enough to pursue and what should be abandoned early. When the system disagrees with itself, I intervene. When it behaves correctly, I largely stay out of its way.

This has uncomfortable implications for teams.

A single developer, equipped with these tools and some discipline around how to use them, can now produce the raw output that would previously have required an entire organization. That does not mean judgment, taste, or architectural sense have become irrelevant. If anything, they matter more, because they are now the limiting factors.

The question facing engineering organizations is not whether this is philosophically satisfying. It is whether they can afford to ignore it. Faced with this kind of leverage, choosing not to experiment starts to look less like prudence and more like denial.

The work itself has changed shape. The job used to be producing code. Increasingly, it is about defining outcomes, setting boundaries, and validating behavior. It feels less like typing and more like directing, less like construction and more like editing.

If you want to dismiss this as “vibe coding,” you can. If you want to worry about what it means for junior engineers or for the craft itself, those concerns are legitimate and worth discussing. But the economics are already here, quietly rearranging incentives.

The multiplier is no longer a nice bonus.

It is the work.

How I Built Real-Time Dashboards for Claude Code Metrics with OTEL, Prometheus, and Grafana

Mike Lane — Wed, 17 Dec 2025 19:54:43 +0000

I wanted to know exactly what I was getting out of Claude Code. Not vibes. Numbers.

So I built some Grafana dashboards that track everything: tokens, cost, lines of code, productivity ratios, ROI. Here's how to set it up yourself.

The Stack

Claude Code with native OTEL telemetry (yes, it has this built in)
Prometheus as the metrics backend
Grafana for visualization

Step 1: Enable OTEL Export from Claude Code

Add these to your shell profile (~/.zshrc or ~/.bashrc):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9090/api/v1/otlp

Restart your terminal or source the file.

Step 2: Configure Prometheus

Prometheus needs two flags to accept OTLP metrics:

prometheus \
  --config.file=prometheus.yml \
  --web.enable-otlp-receiver \
  --enable-feature=otlp-deltatocumulative

If you're using Homebrew on macOS, you might need to edit the service plist or create a wrapper script.

The otlp-deltatocumulative flag is important. Some Claude Code metrics (like lines of code) are delta metrics, not cumulative. This flag handles the conversion automatically.

Step 3: Verify Metrics Are Flowing

Once you've used Claude Code with the new env vars, check that Prometheus is receiving data:

curl 'http://localhost:9090/api/v1/label/__name__/values' | jq '.data[]' | grep claude

You should see metrics like:

claude_code_token_usage_tokens_total
claude_code_cost_usage_USD_total
claude_code_active_time_seconds_total
claude_code_lines_of_code_count_total
claude_code_session_count_total

The Metrics Claude Code Exports

Metric	Labels	What It Tracks
`claude_code_token_usage_tokens_total`	`type` (input/output/cacheRead/cacheCreation), `model`	Token consumption
`claude_code_cost_usage_USD_total`	`model`	Estimated API cost
`claude_code_active_time_seconds_total`	`type` (cli/user)	Time tracking
`claude_code_lines_of_code_count_total`	`type` (added/removed)	Code output (delta metric)

The active_time metric is interesting. cli is how long Claude was working. user is how long you were interacting. The ratio between them is your productivity multiplier.

Step 4: Import the Dashboards

I've created three dashboards:

Claude Code Metrics - Token stats, cost breakdown, productivity ratio
Daily/Weekly Summary - Aggregated stats with time-range awareness
Engineering Economics - ROI calculations, team equivalence, business metrics

The dashboards use Grafana variables so you can customize:

Your hourly rate (for ROI calculations)
Average developer lines/hour (for team equivalence)

Key Queries

Productivity Ratio (CLI time / User time):

sum(claude_code_active_time_seconds_total{type="cli"}) 
/ sum(claude_code_active_time_seconds_total{type="user"})

Lines per Dollar:

sum(sum_over_time(claude_code_lines_of_code_count_total[$__range])) 
/ sum(increase(claude_code_cost_usage_USD_total[$__range]))

Equivalent Developer Hours (assuming 75 lines/hour):

sum(sum_over_time(claude_code_lines_of_code_count_total[$__range])) / 75

Max Plan ROI (for $200/month subscribers):

sum(increase(claude_code_cost_usage_USD_total[$__range])) 
/ (6.67 * ($__range_s / 86400))

A Note on Lines of Code

The lines_of_code metric is a delta metric, not cumulative. This means you need sum_over_time() instead of increase():

# Wrong - will give weird extrapolated values
sum(increase(claude_code_lines_of_code_count_total[$__range]))

# Correct
sum(sum_over_time(claude_code_lines_of_code_count_total[$__range]))

Results

Here's what one hour looked like for me:

27,000 lines of code
11 minutes of my time
362x velocity multiplier
$47K equivalent output value

The productivity ratio peaked at over 10,000x when I had multiple parallel agents running.

Dashboard JSON

I'll put the dashboard JSON files in a GitHub gist. You can import them directly into Grafana via Dashboards → Import.

[Link to gist coming]

What About Datadog/Other Backends?

The OTEL export should work with any OTLP-compatible backend. Just change the endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-backend-endpoint

For Datadog, you'd point to their OTLP intake endpoint. Same metrics, different destination.

What's Next

I'm planning to add:

Alerts when productivity ratio drops (maybe I'm stuck?)
Cost projections based on current burn rate
Comparison panels for different projects

If you build on this, let me know what you come up with.

Announcing Dioxide v1.0.0: Delightful Dependency Injection for Python

Mike Lane — Fri, 12 Dec 2025 14:34:22 +0000

Dioxide v1.0.0 is Here! 🎉

After months of development, I'm thrilled to announce Dioxide v1.0.0 my opinionated, ergonomic dependency injection framework for Python backed by Rust.

What is Dioxide?

Dioxide makes the Dependency Inversion Principle feel inevitable. It's designed to make depending on abstractions (ports) instead of implementations (adapters) trivially easy.

from dioxide import service, adapter, Container, Profile
from typing import Protocol

# Define your port (interface)
class EmailPort(Protocol):
    def send(self, to: str, body: str) -> None: ...

# Business logic depends on abstractions, not infrastructure
@service
class NotificationService:
    def __init__(self, email: EmailPort) -> None:
        self.email = email

    def notify_user(self, user_id: str, message: str) -> None:
        self.email.send(f"{user_id}@example.com", message)

# Production adapter - the only place with real infrastructure
@adapter.for_(EmailPort, profile=Profile.PRODUCTION)
class SendGridAdapter:
    def send(self, to: str, body: str) -> None:
        # Real SendGrid implementation
        pass

# Test adapter - fast, in-memory
@adapter.for_(EmailPort, profile=Profile.TEST)
class FakeEmailAdapter:
    sent: list[tuple[str, str]] = []

    def send(self, to: str, body: str) -> None:
        self.sent.append((to, body))

Why Dioxide?

🦀 Rust-Backed Core

The container internals are written in Rust via PyO3. Why? Because dependency graphs and cycle detection are a perfect fit for Rust's strong type system. The Python API stays Pythonic; Rust handles the graph theory.

🐍 Pythonic API

No XML. No YAML. No Java patterns. Just decorators, type hints, and Protocols — the Python way.

🧪 Testing is Architecture

Dioxide's profile system makes testing a first-class citizen. Swap implementations with a single parameter:

# Production
container = Container(profile=Profile.PRODUCTION)
container.scan(packages=["myapp"])

# Tests - same code, different adapters
container = Container(profile=Profile.TEST)
container.scan(packages=["myapp"])

🔌 Framework Integrations

v1.0.0 ships with integrations for the most popular Python frameworks:

Framework	Install	Features
FastAPI	`pip install dioxide[fastapi]`	Middleware, `Inject()` helper
Django	`pip install dioxide[django]`	Middleware, `inject()` in views
Django REST Framework	`pip install dioxide[drf]`	Works with APIView, ViewSet, @api_view
Django Ninja	`pip install dioxide[ninja]`	Sync and async endpoints
Flask	`pip install dioxide[flask]`	Request hooks, `inject()` helper
Celery	`pip install dioxide[celery]`	Task scoping with `scoped_task`
Click	`pip install dioxide[click]`	CLI command scoping

Quick Start with Django

# settings.py
MIDDLEWARE = [
    "dioxide.django.DioxideMiddleware",
    # ... other middleware
]

# apps.py
from dioxide.django import configure_dioxide
from dioxide import Profile

class MyAppConfig(AppConfig):
    def ready(self):
        configure_dioxide(
            packages=["myapp.services"],
            profile=Profile.PRODUCTION,
        )

# views.py
from dioxide.django import inject

def my_view(request):
    service = inject(MyService)
    return JsonResponse({"result": service.do_work()})

The Philosophy: Fakes Over Mocks

Dioxide encourages fakes over mocks for testing. Instead of complex mock configurations that test mock behavior, use simple in-memory implementations that test real behavior:

@adapter.for_(UserRepository, profile=Profile.TEST)
class FakeUserRepository:
    def __init__(self):
        self.users: dict[str, User] = {}

    def save(self, user: User) -> None:
        self.users[user.id] = user

    def find(self, user_id: str) -> User | None:
        return self.users.get(user_id)

Your tests become simpler, more reliable, and actually test your business logic.

Installation

# Core only
pip install dioxide

# With your framework of choice
pip install dioxide[fastapi]
pip install dioxide[django]
pip install dioxide[flask]

# Multiple frameworks
pip install dioxide[fastapi,celery]

What's Next?

v1.0.0 marks the completion of our Minimum Lovable Product. The API is now stable — no breaking changes until v2.0.

We're exploring:

Multi-binding / collection injection for plugin patterns
Enhanced async support
More framework integrations

Get Involved

📦 PyPI: pypi.org/project/dioxide
📖 Docs: dioxide.readthedocs.io
🐙 GitHub: github.com/mikelane/dioxide
⭐ Star us if you find Dioxide useful!

Dioxide is open source under the MIT license. Contributions welcome!

Announcing pytest-test-categories v1.1.0: Bring Google Testing Philosophy to Python

Mike Lane — Thu, 04 Dec 2025 23:38:12 +0000

The Problem With Most Test Suites

Be honest - how many of these apply to your codebase?

⏱️ Slow CI pipelines because tests have no time budgets
🎲 Flaky tests from network timeouts, race conditions, or shared state
🔺 Inverted test pyramid with too many slow integration tests
🚫 No enforced boundaries between unit, integration, and system tests

If you nodded at any of these, you're not alone. These are the most common testing anti-patterns I see in Python projects.

Enter pytest-test-categories

Today I'm releasing v1.1.0 of pytest-test-categories - a pytest plugin that brings Google's battle-tested testing philosophy (from "Software Engineering at Google") to Python.

pip install pytest-test-categories

What It Does

1. Categorize tests by size with clear resource constraints:

import pytest

@pytest.mark.small
def test_pure_function():
    """Must complete in <1 second, no I/O allowed"""
    assert calculate_total([1, 2, 3]) == 6

@pytest.mark.medium
def test_database_query(db_connection):
    """Can access localhost, up to 5 minutes"""
    result = db_connection.query("SELECT * FROM users")
    assert len(result) > 0

@pytest.mark.large
def test_external_api():
    """Full network access, up to 15 minutes"""
    response = requests.get("https://api.example.com")
    assert response.ok

@pytest.mark.xlarge
def test_extended_e2e():
    """Full access, up to 15 minutes, for extensive E2E tests"""
    # Long-running end-to-end workflow
    pass

2. Enforce hermeticity - When a small test tries to access the network:

======================================================================
[TC001] Network Violation
======================================================================
Category: SMALL

What happened:
  SMALL test attempted network connection to api.example.com:443

To fix this (choose one):
  • Mock the network call using responses, httpretty, or respx
  • Use dependency injection to provide a fake HTTP client
  • Change test category to @pytest.mark.medium
======================================================================

3. Validate your test pyramid - Ensure you maintain the recommended 80/15/5 distribution:

======================== Test Size Distribution ========================
Small:   120 tests (80.0%) - Target: 80% ✓
Medium:   22 tests (14.7%) - Target: 15% ✓
Large:     8 tests ( 5.3%) - Target:  5% ✓
========================================================================

The "No Escape Hatches" Philosophy

Unlike other tools, pytest-test-categories is intentionally strict. There's no @pytest.mark.allow_network marker.

Why? Because escape hatches become the norm:

# This defeats the entire purpose
@pytest.mark.small
@pytest.mark.allow_network  # ❌ This marker doesn't exist!
def test_api():
    requests.get("https://api.example.com")  # Still flaky!

Instead, use the right category:

@pytest.mark.medium  # ✓ Honest about what the test does
def test_api():
    requests.get("https://api.example.com")

Resource Isolation by Test Size

Resource	Small	Medium	Large	XLarge
Time	1s	5min	15min	15min
Network	❌ Blocked	Localhost	✓ Allowed	✓ Allowed
Filesystem	❌ Blocked	✓ Allowed	✓ Allowed	✓ Allowed
Database	❌ Blocked	✓ Allowed	✓ Allowed	✓ Allowed
Subprocess	❌ Blocked	✓ Allowed	✓ Allowed	✓ Allowed
Sleep	❌ Blocked	✓ Allowed	✓ Allowed	✓ Allowed

Mocking Libraries Just Work

Small tests can use mocking libraries like responses, respx, pytest-mock, pyfakefs, and VCR.py without triggering violations. Why? Because mocks intercept at the library layer before reaching the actual resource:

import pytest
import responses
import requests

@pytest.mark.small
@responses.activate
def test_api_with_mock():
    """This is hermetic - no real network call is made."""
    responses.add(
        responses.GET,
        "https://api.example.com/users",
        json={"users": []},
        status=200,
    )

    response = requests.get("https://api.example.com/users")
    assert response.json() == {"users": []}

For filesystem operations in small tests, use pyfakefs or io.StringIO/io.BytesIO for in-memory file handling.

Gradual Adoption

You don't have to go strict on day one:

# pyproject.toml

# Week 1: Discovery - see what would fail
[tool.pytest.ini_options]
test_categories_enforcement = "off"

# Week 2-4: Migration - fix violations incrementally  
test_categories_enforcement = "warn"

# Week 5+: Enforced - violations fail the build
test_categories_enforcement = "strict"

Full pytest-xdist Support

Run your categorized tests in parallel with full support for pytest-xdist:

pytest -n auto

Distribution stats are aggregated correctly across workers, and timer isolation ensures no race conditions.

JSON Reports for CI/CD

Export machine-readable reports for dashboards and CI integration:

pytest --test-size-report=json --test-size-report-file=report.json

{
  "summary": {
    "total_tests": 150,
    "distribution": {
      "small": {"count": 120, "percentage": 80.0},
      "medium": {"count": 22, "percentage": 14.67},
      "large": {"count": 8, "percentage": 5.33}
    },
    "violations": {
      "timing": 0,
      "hermeticity": {
        "network": 0,
        "filesystem": 0,
        "subprocess": 0,
        "database": 0,
        "sleep": 0,
        "total": 0
      }
    }
  }
}

Get Started

pip install pytest-test-categories

Then mark your tests and enable enforcement:

# pyproject.toml
[tool.pytest.ini_options]
test_categories_enforcement = "warn"

Links

I'd love to hear your feedback! Have questions or feature requests? Open an issue on GitHub or drop a comment below.

Happy testing! 🧪

Forem: Mike Lane

Your Mutation Testing Tool Should Make You Explain Yourself

Announcing pytest-gremlins v1.3.0

Mutation Testing That Actually Fits Into Your Workflow

What Is pytest-gremlins?

Four mechanisms drive its speed:

Getting Started

What's New in v1.3.0

--gremlin-workers Now Implies Parallel Mode

--gremlins --cov Actually Works Now

Clear Error When Combining with pytest-xdist

Windows Path Fix

Subprocess Isolation

Typical Output

pyproject.toml Configuration

Performance Numbers

Links

Replacing 800 Lines of AI Agent Instructions with 10-Token Questions

The Problem

"Are Your Lights On?"

The Mechanism

TDD Discipline: Bracketing the Decision

Error Recovery: Three Questions for Three Assumptions

When Questions Are Not Enough

The Full System

Build Your Own

The Sign at the Exit

Your Tests Pass. But Would They Catch This Bug?

Why Mutation Testing Has Been Impractical

pytest-gremlins Architecture

Benchmark: pytest-gremlins vs mutmut

Installation and Usage

Configuration

Try It On Your Code

Dioxide v2.0.0: Clean Architecture Made Simple

What is Dioxide?

What's New in v2.0.0

Auto-Scan via Constructor

Extensible Custom Profiles

Container Introspection

Pytest Fixtures

Breaking Changes

Why Dioxide?

Get Started

dioxide v1.1.2: Multi-Binding for Plugin Systems

Plugin Systems

Ordered Processing Pipelines

Profile-Filtered Collections

Constraints and Behavior

Links

Building Guardrails for AI Coding Assistants: A PreToolUse Hook System for Claude Code

The Hook Contract

Hook 1: Safety Guards

Hook 2: Context Injection for GitHub API Calls

Hook 3: Workflow Rule Enforcement

Hook 4: Skill Suggestion Engine

Hook Configuration

Observations

Implementation Considerations

CLI Validation Patterns with Maybe Monads

CLI Validation Patterns with Maybe Monads

The Problem with Nested Exception Handling

Pattern 1: Chained Validation with bind

Pattern 2: Combining Validators with Operators

Pattern 3: Filesystem Validation Pipelines

Pattern 4: Interactive Prompts with Retry Logic

Integrating with argparse

Tradeoffs

Summary

The Multiplier Is the Job Now: Why Agentic AI Changes Everything

How I Built Real-Time Dashboards for Claude Code Metrics with OTEL, Prometheus, and Grafana

The Stack

Step 1: Enable OTEL Export from Claude Code

Step 2: Configure Prometheus

Step 3: Verify Metrics Are Flowing

The Metrics Claude Code Exports

Step 4: Import the Dashboards

Key Queries

A Note on Lines of Code

Results

`--gremlin-workers` Now Implies Parallel Mode

`--gremlins --cov` Actually Works Now