TDD Guard

Automated TDD enforcement for Claude Code.

Overview

TDD Guard monitors file operations in real-time and blocks any changes that violate TDD principles. By analyzing test results, todos, and code changes, it ensures Claude Code follows the red-green-refactor cycle without manual reminders.

Click to watch TDD Guard in action

Why TDD Guard?

• Focus on solving problems - TDD Guard enforces the rules while you design solutions
• Save context for what matters - No more TDD instructions cluttering your CLAUDE.md
• Works with your stack - TypeScript, JavaScript, and Python today. More languages coming soon
• Control without context switches - Toggle with tdd-guard on/off mid-session
• Flexible validation - Use local Claude or configure Anthropic API

Requirements

• Node.js 18+
• Test Runner:
  • JavaScript/TypeScript: Vitest
  • Python: pytest

Quick Start

1. Install TDD Guard

npm install -g tdd-guard

2. Set Up Test Reporter

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

JavaScript/TypeScript (Vitest)

Install the reporter in your project:

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

Add to your vitest.config.ts:

import { VitestReporter } from 'tdd-guard-vitest'

export default defineConfig({
  test: {
    reporters: ['default', new VitestReporter()],
  },
})

Note: Using workspaces or monorepos? See the workspace configuration guide for additional setup steps.

Python (pytest)

Install the reporter:

pip install tdd-guard-pytest

No configuration needed - the pytest plugin activates automatically when installed.

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...
4. Enter: Write|Edit|MultiEdit|TodoWrite
5. Select + Add new hook...
6. Enter command: tdd-guard
7. Choose where to save (Project settings recommended)

Tip: Also configure quick commands for tdd-guard on/off and ESLint integration for automated refactoring support.

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.

Known Limitations

• Not tested with multiple subagents in the same project

Roadmap

• Add support for more testing frameworks (Jest, Mocha, unittest, etc.)
• Add support for additional programming languages (Go, Rust, Java, etc.)
• Encourage meaningful refactoring opportunities when tests are green
• Add support for multiple concurrent subagents per project

Contributing

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

Contributors:

• Python/pytest support: @Durafen

Learn More

• Configuration Guide - Environment variables, model options, and troubleshooting
• Architecture Decision Records - Technical design decisions and rationale

License

MIT