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.

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 - Choose faster or more capable models for your needs
• Session Control - Toggle on and off mid-session

Requirements

• Node.js 22+
• 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

Using npm:

npm install -g tdd-guard

Or using Homebrew:

brew install tdd-guard

2. Add Test Reporter

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

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

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).

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.

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.

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 Hooks

TDD Guard uses hooks to validate operations and provide convenience features like quick toggle commands and automatic session management.

Choose either interactive or manual setup below:

Type /hooks in Claude Code to open the hooks menu, then configure each hook. Use the same location for all hooks. See Settings File Locations for guidance.

PreToolUse Hook

1. Select PreToolUse - Before tool execution
2. Choose + Add new matcher... and enter: Write|Edit|MultiEdit|TodoWrite
3. Select + Add new hook... and enter: tdd-guard
4. Choose where to save

UserPromptSubmit Hook

1. Select UserPromptSubmit - When the user submits a prompt
2. Select + Add new hook... and enter: tdd-guard
3. Choose same location as PreToolUse

SessionStart Hook

1. Select SessionStart - When a new session is started
2. Select + Add new matcher... and enter: startup|resume|clear
3. Select + Add new hook... and enter: tdd-guard
4. Choose same location as previous hooks

If you prefer to edit settings files directly, add all three hooks to your chosen settings file. See Settings File Locations to choose the appropriate file:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit|TodoWrite",
        "hooks": [
          {
            "type": "command",
            "command": "tdd-guard"
          }
        ]
      }
    ],
    "userpromptsubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "tdd-guard"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume|clear",
        "hooks": [
          {
            "type": "command",
            "command": "tdd-guard"
          }
        ]
      }
    ]
  }
}

Additional Configuration

• Custom instructions - Customize TDD validation rules
• Lint integration - Automated refactoring support
• Strengthening enforcement - Prevent agents from bypassing validation
• Ignore patterns - Control which files are validated
• Validation Model - Choose faster or more capable model

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
• Go support: @sQVe, @wizzomafizzo

Support

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

License

MIT