Sandbox
Sign in
@nizos/tdd-guard
Hooks#Claude Code#Coding#Testing#Code review

Claude Code hooks for test-first enforcement

TDD Guard adds Claude Code hooks that check whether an agent is following TDD before it keeps going. It uses validation rules, lint integration, and test reporters to catch missing tests or premature implementation, then tells the agent what to do next.

2,335 stars•186 forks•TypeScript•Updated 10d ago
Who it's for

Builders who use Claude Code and want test-first rules enforced while the agent writes code.

What it delivers

You can stop your agent from skipping tests or over-implementing, and keep work aligned with TDD.

What it does

Test-first enforcement

Blocks implementation when there are no failing tests to justify the change.

Minimal implementation checks

Prevents code changes that go beyond the current test requirements.

Lint integration

Uses your lint rules to push refactoring and cleanup.

Custom validation rules

Lets you adjust enforcement to match your TDD style.

Session control

Lets you toggle enforcement on and off during a session.

Multi-framework test reporting

Supports reporters for Vitest, Jest, Storybook, pytest, PHPUnit, Go, Rust, RSpec, and Minitest.

How to get it

  1. 1Open Claude Code in your project and run
    /plugin marketplace add nizos/tdd-guard
  2. 2Run
    /plugin install tdd-guard@tdd-guard
  3. 3Run
    /tdd-guard:setup

README

TDD Guard

npm version npm downloads CI Security License: MIT

[!IMPORTANT] TDD Guard grew into Probity: the same TDD enforcement, now for Claude Code, Codex, and GitHub Copilot CLI, with 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.

Automated Test-Driven Development enforcement for Claude Code.

TDD Guard blocking TDD violations

TDD Guard ensures Claude Code follows Test-Driven Development principles. When your agent tries to skip tests or over-implement, TDD Guard blocks the action and explains what needs to happen instead.

Features

  • Test-First Enforcement - Blocks implementation without failing tests
  • Minimal Implementation - Prevents code beyond current test requirements
  • Lint Integration - Enforces refactoring using your linting rules
  • Customizable Rules - Adjust validation rules to match your TDD style
  • Flexible Validation - Choose faster or more capable models for your needs
  • Session Control - Toggle on and off mid-session

Getting Started

Requirements

  • Node.js 22+
  • A supported test framework (Vitest, Jest, Storybook, pytest, PHPUnit, Go, Rust, RSpec, Minitest)

Installation

Open Claude Code in your project and run:

  1. /plugin marketplace add nizos/tdd-guard
  2. /plugin install tdd-guard@tdd-guard
  3. /tdd-guard:setup

This adds the marketplace, installs the plugin, and configures the test reporter for your project. You may need to restart your terminal session or IDE extension for the setup skill to appear. For manual installation and configuration, see the installation guide.

Configuration

Security

TDD Guard hooks run with your user permissions. We maintain automated security scanning, dependency audits, and welcome source code review. See Claude Code's security considerations for more on hook safety.

Development

Contributing

Contributions are welcome! See the contributing guidelines to get started.

Contributors:

Support

  • Discussions - Ask questions and share ideas
  • Issues - Report bugs and request features

License

MIT

Files in the repo

Repository payload•29 top-level entries
  • .claude-plugin
  • .devcontainer
  • .github
  • .husky
  • docs
  • plugin
  • reporters
  • src
  • test
  • .claudeignore
  • .commitlintrc.json
  • .env.example
  • .gitignore
  • .npmignore
  • .prettierignore
  • .prettierrc
  • CLAUDE.md
  • CONTRIBUTING.md
  • DEVELOPMENT.md
  • eslint.config.mjs
  • LICENSE
  • package-lock.json
  • package.json
  • README.md
  • tsconfig.build.json
  • tsconfig.eslint.json
  • tsconfig.json
  • tsconfig.node.json
  • vitest.config.ts

Discussion (0)

Ask about usage, or say what you built with it

Sign in to join the discussion.

No comments yet. Be the first to say what this is good for.

More hooks

rtk-ai/rtkHooks

CLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies

80k
PeonPing/peon-pingHooks

Warcraft III Peon voice notifications (+ more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.

5k
bahni-m/
code-with-quran
bahni-m/code-with-quranHooks

Read the Qur'an while Claude Code works. Start a session with 'claude --cwq' and a reader beside it walks forward through the Qur'an one ayah per prompt, resuming where you left off — in a terminal pane or a browser tab. Zero dependencies, fully offline.

48
zachahn/
vomit
zachahn/vomitHooks

Clean up Claude's token vomit with a separate LLM. Save your tokens, Opus is hopeless

193
kenryu42/cc-safety-netHooks

A pre-execution guard for AI coding agents. It blocks destructive Git and file system commands, plus common attempts to access sensitive files, before a tool call runs. Supports Amp Code, Antigravity CLI, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, Grok Build, Hermes Agent, Kimi Code, OpenClaw, OpenCode, and Pi.

1.5k