TDD Guard is an automated enforcement tool for the Test-Driven Development (TDD) red-green-refactor cycle, designed for developers using Claude Code. It monitors file operations in real-time, analyzing test results, to ensure adherence to TDD principles without manual intervention, thereby helping developers maintain focus and save context.

How It Works

TDD Guard operates by integrating with popular test runners (Vitest, pytest, PHPUnit) via custom reporters. These reporters capture test outcomes and file changes, feeding this data to TDD Guard. The tool then analyzes this information against TDD principles, blocking non-compliant file modifications. This real-time validation loop aims to automate the discipline of TDD, reducing cognitive load for developers.

Quick Start & Requirements

• Install: npm install -g tdd-guard
• Prerequisites: Node.js 18+, Vitest (JS/TS), pytest (Python), or PHPUnit 9.x-12.x (PHP).
• Setup: Requires installing language-specific reporters (e.g., npm install --save-dev tdd-guard-vitest) and configuring them within test runner configurations (vitest.config.ts, pyproject.toml, phpunit.xml), often specifying the project root. Claude Code hooks must also be configured to trigger tdd-guard.
• Docs: Vitest Reporter, Pytest Reporter

Highlighted Details

• Real-time file operation monitoring and blocking.
• Supports JavaScript/TypeScript (Vitest), Python (pytest), and PHP (PHPUnit).
• Integrates with Claude Code via custom hooks for automated enforcement.
• Offers configuration for local Claude or Anthropic API.

Maintenance & Community

• Contributions are welcome via issues and pull requests.
• Community support channels are not explicitly mentioned.

Licensing & Compatibility

• License: MIT.
• Compatibility: Permissive MIT license allows for commercial use and integration with closed-source projects.

Limitations & Caveats

The tool is not yet tested with multiple concurrent sessions in the same project and has a roadmap to support more testing frameworks and programming languages. Users must be aware of the security implications of Claude Code hooks, as they execute shell commands with user permissions.