TDD enforcement for Claude Code.

TDD Guard monitors file operations in real-time and blocks changes that violate TDD principles. It provides immediate feedback when violations occur, helping maintain disciplined development practices without manual oversight.

The tool intercepts Write, Edit, and MultiEdit operations before execution, examining them against the current development state. Each validation considers the file path, intended modifications, current todo list, and latest test results to determine whether changes follow proper TDD practices.

• Eliminates manual TDD enforcement: No need to remind agents about writing tests first or following TDD cycles
• Preserves context window: Removes lengthy TDD instructions from CLAUDE.md, freeing space for domain-specific guidance
• Maintains development flow: Works silently until a violation occurs, then provides clear corrective feedback

• Multi-model Support: Choose between Claude Code CLI or Anthropic API
• Context Aggregation: Combines file modifications, todo states, and test results for accurate validation
• Dynamic Instructions: Tailored prompts for Write, Edit, and MultiEdit operations
• Task-Based Enforcement: Automatically adjusts TDD rules based on task complexity and type

npm install --save-dev tdd-guard

If you do not have Claude installed locally, create a .env file:

USE_SYSTEM_CLAUDE=true

This tells TDD Guard to the System Claude from PATH instead of ~/.claude/local/claude.

Configure TDD Guard using the /hooks command:

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)

Add to your vitest.config.ts:

import { VitestReporter } from 'tdd-guard'

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

For advanced configuration options, see the Configuration Guide.

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.

• Not tested with multiple subagents working simultaneously
• Test output context only available for Vitest

• Encourage meaningful refactoring opportunities when tests are green
• Add support for other testing frameworks (Jest, Mocha, etc.)
• Improve handling of concurrent subagents

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

• Configuration Guide
• Task-Based TDD Enforcement - NEW!
• Architecture Decision Records

MIT