TDD Guard
github.com/nizos/tdd-guard- Category
- Developer Tools
- Rank
- No. 416Tools index
- Pricing
- Open Source
- Platform
- cli
- Type
- TOOL
- Builder
- nizos
- GitHub
- 2.3k stars
- Latest release
- v1.7.0
- Added
- Jul 4, 2026
About
TDD Guard is a Claude Code plugin that automatically enforces Test-Driven Development principles during AI-assisted coding sessions. It blocks implementation attempts without failing tests, prevents over-implementation, and integrates with your linter to enforce the full red-green-refactor cycle. Supports Vitest, Jest, pytest, PHPUnit, Go, Rust, RSpec, and more.
What it does
TDD Guard watches Claude Code tool events, records edits and test context, then asks a configurable model client whether work should continue. It can also run lint checks after edits, preserve issue state between hooks, ignore selected files, and explain blocked actions.
Why it's ranked here
The project offers unusually concrete control over agent coding behavior: persistent hook context, configurable validation clients, schema-checked inputs, lint feedback, and session controls. Its own README now directs new projects to Probity, however, making TDD Guard chiefly relevant to existing Claude Code setups.
What's good
Configuration supports SDK, CLI, or API validation clients, custom instructions, model selection, ignore patterns, and optional linting. Stored context covers modifications, tests, tasks, lint findings, and instructions. Tests verify CLI behavior, persistence, path validation, context building, and detailed ignore-pattern matching.
Tradeoffs
It requires Node.js 22 or newer and reporter configuration for supported test frameworks. Hooks run with the user’s permissions, so their security boundary deserves scrutiny. Invalid CLI input reports an error but still exits successfully. The maintainers recommend Probity for new projects because its validation is more reliable and needs no test reporters.
How to use it well
Use it in an established Claude Code project where strict, model-assisted TDD enforcement justifies reporter setup and persistent hook state. Tune instructions, validation client, lint integration, and ignore patterns to the repository. Choose Probity instead for a new project or when Codex, GitHub Copilot CLI, or reporter-free validation matters.
Technical notes+
package.json defines a Node.js 22+ TypeScript package with an npm CLI binary, library entry points, three reporter workspaces, and Anthropic SDK dependencies. src/cli/tdd-guard.ts reads hook JSON from stdin, builds Config, FileStorage, ModelClientProvider, and validator dependencies, prints only blocking results, and exits zero even after parsing errors. src/config/Config.ts selects sdk, cli, or api validation, stores state under .claude/tdd-guard/data, and validates the Claude project directory. src/hooks/HookEvents.ts persists todo operations separately from other modifications. src/cli/buildContext.ts combines modifications, tests, todos, lint data, and custom instructions. src/hooks/postToolLint.ts runs a configured linter after tool use and blocks when previously reported issues remain. src/guard/GuardManager.ts defaults the guard on and applies minimatch-based ignore patterns. The supplied tests cover these behaviors.
Observed
- License
- MIT
- Primary language
- TypeScript
- Packaging
- npm package with CLI binary and library entry points
- Runtime
- Node.js 22 or newer
- Primary interface
- Claude Code plugin and stdin-driven hook CLI
- Validation clients
- Anthropic SDK, Claude CLI, or API
- Supported test frameworks
- Vitest, Jest, Storybook, pytest, PHPUnit, Go, Rust, RSpec, and Minitest
- Reporter workspaces
- Vitest, Jest, and Storybook
Read from README.md, package.json, src/index.ts, src/cli/tdd-guard.ts, src/config/Config.ts, src/processors/index.ts, src/cli/buildContext.ts, src/hooks/HookEvents.ts, src/cli/tdd-guard.test.ts, src/config/Config.test.ts, src/guard/GuardManager.ts, src/hooks/postToolLint.ts, src/cli/buildContext.test.ts, src/hooks/HookEvents.test.ts, src/guard/GuardManager.test.ts.
What it can do
Block implementation code generation without prior failing tests
AI coding attempt without corresponding failing test → Blocked action with enforcement message requiring a failing test first
Enforce red-green-refactor TDD cycle
AI-assisted coding session in Claude Code → Guided workflow that sequences test writing, passing, and refactoring steps
Prevent over-implementation beyond test requirements
AI-generated implementation code exceeding what failing tests specify → Blocked or flagged code with restriction to minimal passing implementation
Integrate linter checks into TDD workflow
Code changes during a TDD session → Linting results enforced as part of the refactor phase gate
Apply custom TDD enforcement rules
User-defined configuration rules for TDD behavior → Customized enforcement policies applied during AI coding sessions
Support multi-language test framework detection
Project using Vitest, Jest, pytest, PHPUnit, Go, Rust, or RSpec tests → Automatically recognized test framework with appropriate enforcement applied
Tags
Tech Stack
Media
Comments (0)
No comments yet
Indexed by a proprietary survey. Corrections welcome.