TDD Guard

Automated Test-Driven Development enforcement for Claude Code.

Overview

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—enforcing the red-green-refactor cycle automatically.

Click to watch TDD Guard in action

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
• Multi-Language Support - TypeScript, JavaScript, Python, PHP, Go, and Rust
• Customizable Rules - Adjust validation rules to match your TDD style
• Flexible Validation - Use local Claude or faster Anthropic API
• Session Control - Toggle on and off mid-session

Requirements

• Node.js 18+
• Claude Code or Anthropic API key
• Test framework (Jest, Vitest, pytest, PHPUnit, Go 1.24+, or Rust with cargo/cargo-nextest)

Quick Start

1. Install TDD Guard

npm install -g tdd-guard

2. Add Test Reporter

TDD Guard needs to capture test results from your test runner. Choose your language below:

JavaScript/TypeScript

Choose your test runner:

Vitest

Install the tdd-guard-vitest reporter in your project:

npm install --save-dev tdd-guard-vitest

Add to your vitest.config.ts:

import { defineConfig } from 'vitest/config'
import { VitestReporter } from 'tdd-guard-vitest'

export default defineConfig({
  test: {
    reporters: [
      'default',
      new VitestReporter('/Users/username/projects/my-app'),
    ],
  },
})

Jest

Install the tdd-guard-jest reporter in your project:

npm install --save-dev tdd-guard-jest

Add to your jest.config.ts:

import type { Config } from 'jest'

const config: Config = {
  reporters: [
    'default',
    [
      'tdd-guard-jest',
      {
        projectRoot: '/Users/username/projects/my-app',
      },
    ],
  ],
}

export default config

Note: For both Vitest and Jest, specify the project root path when your test config is not at the project root (e.g., in workspaces or monorepos). This ensures TDD Guard can find the test results. See the reporter configuration docs for more details:

• Vitest configuration
• Jest configuration

Python (pytest)

Install the tdd-guard-pytest reporter:

pip install tdd-guard-pytest

Configure the project root in your pyproject.toml:

[tool.pytest.ini_options]
tdd_guard_project_root = "/Users/username/projects/my-app"

Note: Specify the project root path when your tests run from a subdirectory or in a monorepo setup. This ensures TDD Guard can find the test results. See the pytest reporter configuration for alternative configuration methods (pytest.ini, setup.cfg).

PHP (PHPUnit)

Install the tdd-guard/phpunit reporter in your project:

composer require --dev tdd-guard/phpunit

For PHPUnit 9.x, add to your phpunit.xml:

<listeners>
    <listener class="TddGuard\PHPUnit\TddGuardListener">
        <arguments>
            <string>/Users/username/projects/my-app</string>
        </arguments>
    </listener>
</listeners>

For PHPUnit 10.x/11.x/12.x, add to your phpunit.xml:

<extensions>
    <bootstrap class="TddGuard\PHPUnit\TddGuardExtension">
        <parameter name="projectRoot" value="/Users/username/projects/my-app"/>
    </bootstrap>
</extensions>

Note: Specify the project root path when your phpunit.xml is not at the project root (e.g., in subdirectories or monorepos). This ensures TDD Guard can find the test results. The reporter saves results to .claude/tdd-guard/data/test.json.

Go

Install the tdd-guard-go reporter:

go install github.com/nizos/tdd-guard/reporters/go/cmd/tdd-guard-go@latest

Pipe go test -json output to the reporter:

go test -json ./... 2>&1 | tdd-guard-go -project-root /Users/username/projects/my-app

For Makefile integration:

test:
	go test -json ./... 2>&1 | tdd-guard-go -project-root /Users/username/projects/my-app

Note: The reporter acts as a filter that passes test output through unchanged while capturing results for TDD Guard. See the Go reporter configuration for more details.

Rust

Install the tdd-guard-rust reporter:

cargo install tdd-guard-rust

Use it to capture test results from cargo test or cargo nextest:

# With nextest (recommended)
cargo nextest run 2>&1 | tdd-guard-rust --project-root /Users/username/projects/my-app --passthrough

# With cargo test
cargo test -- -Z unstable-options --format json 2>&1 | tdd-guard-rust --project-root /Users/username/projects/my-app --passthrough

For Makefile integration:

test:
	cargo nextest run 2>&1 | tdd-guard-rust --project-root $(PWD) --passthrough

Note: The reporter acts as a filter that passes test output through unchanged while capturing results for TDD Guard. See the Rust reporter configuration for more details.

3. Configure Claude Code Hook

Use the /hooks command in Claude Code:

1. Type /hooks in Claude Code
2. Select PreToolUse - Before tool execution
3. Choose + Add new matcher... and enter: Write|Edit|MultiEdit|TodoWrite
4. Select + Add new hook... and enter: tdd-guard
5. Choose where to save (Project settings recommended)

See Strengthening TDD Enforcement to prevent agents from bypassing validation.

Configuration

Quick Setup:

• Toggle commands - Enable/disable with tdd-guard on/off
• Session clearing - Automatic cleanup on new sessions
• Custom instructions - Customize TDD validation rules
• Ignore patterns - Control which files are validated

Advanced:

• ESLint integration - Automated refactoring support
• AI Models - Switch between Claude CLI and Anthropic API

Note: If TDD Guard can't find Claude, see Claude Binary Setup.

Security Notice

As stated in the Claude Code Hooks documentation:

Hooks execute shell commands with your full user permissions without confirmation. You are responsible for ensuring your hooks are safe and secure. Anthropic is not liable for any data loss or system damage resulting from hook usage.

We share this information for transparency. Please read the full security considerations before using hooks.

TDD Guard runs with your user permissions and has access to your file system. We follow security best practices including automated security scanning, dependency audits, and test-driven development. Review the source code if you have security concerns.

Roadmap

• Add support for more testing frameworks (Mocha, unittest, etc.)
• Add support for additional programming languages (Ruby, Java, C#, etc.)
• Validate file modifications made through MCPs and shell commands
• Add integration for OpenCode and other vendor-agnostic AI coding tools
• Encourage meaningful refactoring opportunities when tests are green
• Add support for multiple concurrent sessions per project

Development

• Development Guide - Setup instructions and development guidelines
• Architecture Decision Records - Technical design decisions and rationale

Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

Contributors:

• Python/pytest support: @Durafen
• PHP/PHPUnit support: @wazum
• Rust/cargo support: @104hp6u

Support

• Configuration - Complete settings documentation
• Discussions - Ask questions and share ideas
• Issues - Report bugs and request features

License

MIT