TDD Guard: a Claude Code hook that blocks edits made without a failing test, and the notice that points new projects to Probity

The README's first notice says TDD Guard grew into Probity

An important block at the top of the README says TDD Guard grew into a project called Probity. Probity keeps the same TDD enforcement but covers Claude Code, Codex and GitHub Copilot CLI, with what the README calls more reliable validation and no test reporters to set up. New projects should start there. TDD Guard remains maintained for the projects that rely on it.

That changes how to read everything below the notice. This repository is the Claude Code-only line, and its distinguishing cost is the reporter: each supported framework needs a reporter that writes test results where the hook can read them. Probity is described as removing that requirement.

The last push to this repository was on 12 October 2026, and v1.7.0 is dated 23 June 2026, so the maintenance claim has recent commits behind it. The repository is not archived. An existing user has no urgency to move, while a new user has a stated recommendation to look at the successor first.

The words 'more reliable validation' in the Probity notice are the maintainer's own comparison, and the README gives no numbers behind it. Read it as the author's reason for redirecting new users, not as a measured result.

Three slash commands install it: marketplace, plugin, setup

Installation happens inside Claude Code, in your project:

/plugin marketplace add nizos/tdd-guard
/plugin install tdd-guard@tdd-guard
/tdd-guard:setup

The README says these three steps add the marketplace, install the plugin and configure the test reporter for the project. The setup skill may not appear until you restart your terminal session or IDE extension, a detail that explains a common first-run stall. A manual route exists in `docs/installation.md`.

The requirements are Node.js 22 or newer and a supported test framework. `package.json` repeats the Node floor as `"node": ">=22.0.0"` under engines. The package also ships a CLI named `tdd-guard`, pointing to `dist/cli/tdd-guard.js`, so the npm package and the plugin are two entry points into the same code.

The `.claude-plugin/` and `plugin/` directories at the repository root hold what Claude Code reads.

Some of the files in the root tell you what the project assumes about your machine. `.claudeignore` keeps files away from Claude Code, `.devcontainer/` offers a container setup, and `.npmignore` with the `files` list in `package.json` decides what reaches the npm package: only `dist`, the README and the LICENSE.

What a blocked action looks like: tests first, minimal code, then lint-driven refactoring

When the agent tries to skip tests or over-implement, TDD Guard blocks the action and explains what needs to happen instead. The feature list breaks that into rules.

Test-first enforcement blocks implementation without failing tests. Minimal implementation prevents code beyond what the current test requires. Lint integration enforces refactoring using your linting rules, so the refactor phase of red, green, refactor has a check too. Customizable rules let you adjust validation to match your TDD style, and session control lets you toggle the guard off and on mid-session.

The lint feature has a switch in `.env.example`: `LINTER_TYPE` accepts `eslint` or `golangci-lint`, and when unset there is no linting. The comment says to set it only if you want automatic code quality checks during refactoring.

One consequence is that the guard has opinions about what counts as minimal. If your style differs, the custom instructions document is where you change that.

Nine test frameworks, each with a reporter contributed by a different person

The README names the supported frameworks: Vitest, Jest, Storybook, pytest, PHPUnit, Go, Rust, RSpec and Minitest. In the repository, the npm workspaces are `reporters/vitest`, `reporters/jest` and `reporters/storybook`. Other languages have their own reporters, and the release list includes `minitest-v0.2.0`, labelled tdd-guard-minitest v0.2.0, from 16 May 2026.

The contributors section credits individuals by language: Python and pytest, PHP and PHPUnit, Rust and cargo, Go (two people), Storybook, and Ruby with RSpec and Minitest. That split matters for expectations. Each integration was written by someone who uses that stack, and the JavaScript reporters live in the main package workspaces.

If your framework is not on the list, TDD Guard has nothing to read test results from, and the README gives no generic fallback. Whether a tool like Playwright fits is not covered. The `pretest:reporters` script installs Chromium for the reporter tests, which suggests that part of the test suite needs a browser.

The README does not say how reporters behave in a monorepo with several test frameworks at once, or what happens when a test run is slow. Check both on your own project, since a guard that waits on stale results can block correct edits.

Validation is a model call: sdk by default, api with a key, claude-sonnet-4-0 unless you change it

The decision to block an edit is made by a language model, not by a rule engine. `.env.example` shows the controls. `VALIDATION_CLIENT` is either `sdk` (the default) or `api`. `TDD_GUARD_MODEL_VERSION` defaults to `claude-sonnet-4-0`. `TDD_GUARD_ANTHROPIC_API_KEY` is required only when the client is set to `api`.

The README advertises flexible validation: choose a faster or a more capable model for your needs, with a page at `docs/validation-model.md`. A faster model returns sooner on each edit; a more capable one is described as the better judge. The trade is yours to make, since every guarded edit waits on a validation call.

Because the verdict comes from a model, it can be wrong in both directions. The README documents no accuracy figures. The settings reference is in `docs/configuration.md`, and the README calls it complete settings documentation.

The README gives no figure for how long a validation call takes or what it costs per edit. With `api` as the client you pay for tokens through your own Anthropic key, so track the first day of use before leaving it on for a whole team.

The hooks run with your permissions, and agents can try to route around them

The security section states plainly that TDD Guard hooks run with your user permissions. It lists automated security scanning and dependency audits, and invites source review, then points to Claude Code's own security considerations for hooks. The repository has a CI workflow and a separate security workflow, according to its badges.

A second risk sits on the other side: the guard can be bypassed. There is a document titled strengthening enforcement, at `docs/enforcement.md`, whose description is preventing agents from bypassing validation. Its existence tells you the failure case is real enough to document, though the README does not list the specific bypass methods.

Ignore patterns control which files get validated, in `docs/ignore-patterns.md`. A file outside validation is a file the agent can edit freely, so keep that list short. Configuration, test and documentation files are the usual candidates, but the README gives no recommended defaults.

The README also lists what to read next, all under `docs/`: `custom-instructions.md` for validation rules, `linting.md` for automated refactoring support, `enforcement.md`, `ignore-patterns.md`, `validation-model.md` and `configuration.md`. Six documents for a tool this size means most real adoption questions are answered outside the README, so budget time to read them before you rely on the guard for a team.

Developing on it: a monorepo with Vitest projects and a husky pre-commit

The development setup shows how much machinery sits behind the plugin. Scripts include `build`, which compiles with `tsc --build tsconfig.build.json` and then builds the workspaces, plus separate test commands: `test`, `test:unit`, `test:integration` and `test:reporters`, all through Vitest projects. A `checks` script chains typecheck, lint, format and test. The lint script runs with `--max-warnings 0`, so a warning fails it.

Husky and commitlint are configured (`.husky/`, `.commitlintrc.json`), and there is a `.devcontainer/` directory. `CONTRIBUTING.md` and `DEVELOPMENT.md` hold the contribution rules, and `CLAUDE.md` is in the repository, which fits a project built with the tool it enforces rules on.

Support goes through GitHub Discussions for questions and Issues for bugs. The license is MIT and the author field names Nizar Selander. The version in `package.json` is 1.7.0, matching the latest release, and the earlier v1.6.9 followed a week before.

The lint script uses `--fix`, while `lint:check` does not, so the first rewrites files and the second only reports. Use `lint:check` in CI. The `format` script runs `prettier --write .` across the whole repository, which can touch files unrelated to your change.

The full test suite includes a `golangci-lint` Vitest project alongside the default and unit projects, so a contributor needs that linter available to run `npm test` cleanly.

Editorial conclusion

Use TDD Guard if you work in Claude Code on a project that already has one of the supported test frameworks and you want over-implementation blocked before it lands. Start with Probity instead if you are beginning a new project or use Codex or GitHub Copilot CLI, since the README says new projects should begin there. Before adopting, run the setup command and then read docs/enforcement.md, because the hooks run with your user permissions and the README admits agents can try to bypass validation.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nizos/tdd-guard on GitHub
4. README
5. Releases