Quick Start & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/cli/tdd-guard.ts
• DEVELOPMENT.md
• CLAUDE.md
• src/config/Config.test.ts
• CONTRIBUTING.md

TDD Guard is an automated Test-Driven Development (TDD) enforcement tool designed specifically for Claude Code. It intercepts file operations such as Write, Edit, and MultiEdit to ensure that an AI agent follows TDD principles—specifically the Red-Green-Refactor cycle. By analyzing test results and code changes in real-time, it blocks operations that skip tests or over-implement logic.

The system consists of a core TypeScript CLI application and several language-specific reporters that capture test results from various frameworks including Vitest, Jest, pytest, PHPUnit, Go, and Rust. Sources: README.md:8-15, CLAUDE.md:5-12

Installation

TDD Guard can be installed globally via package managers to make the tdd-guard binary available for Claude Code hooks.

Method	Command
npm	npm install -g tdd-guard
Homebrew	brew install tdd-guard

Sources: README.md:33-41

1. Add Test Reporter

TDD Guard requires a reporter to capture and save test results to .claude/tdd-guard/data/test.json. This allows the validator to verify if implementation changes are justified by failing tests. Sources: README.md:120, reporters/rust/src/main.rs:163-170

JavaScript/TypeScript Setup

For Vitest or Jest, install the corresponding reporter and update your configuration file.

// vitest.config.ts example
import { VitestReporter } from 'tdd-guard-vitest'

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

Sources: README.md:52-70

Other Languages

• Python: Install tdd-guard-pytest and configure tdd_guard_project_root in pyproject.toml.
• Go: Install tdd-guard-go and pipe test output: go test -json ./... 2>&1 | tdd-guard-go -project-root /path/to/project.
• Rust: Install tdd-guard-rust and use cargo nextest run 2>&1 | tdd-guard-rust --project-root /path/to/project --passthrough.

Sources: README.md:112-167

2. Configure Claude Code Hooks

TDD Guard integrates with Claude Code using three primary hooks. These hooks allow the tool to capture the context of the AI's actions before they are executed. Sources: README.md:175-180, CLAUDE.md:7-12

The following diagram illustrates the flow of a tool operation through the TDD Guard validation process:

The PreToolUse hook is the critical checkpoint where Write, Edit, and MultiEdit operations are validated against current test states. Sources: README.md:188-193, src/cli/tdd-guard.test.ts:70-95

Manual Hook Configuration

Add the following to your Claude Code settings 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" }]
    }]
  }
}

Sources: README.md:214-250

Configuration Options

TDD Guard behavior can be customized via environment variables or a config.json file located in the data directory. Sources: src/config/Config.test.ts:25-50

Variable	Description	Default
VALIDATION_CLIENT	API client to use (cli, sdk, or api)	cli
MODEL_TYPE	Legacy version of validation client	claude_cli
TDD_GUARD_MODEL_VERSION	Specific Claude model version	Internal Default
CLAUDE_PROJECT_DIR	Absolute path to the project root	Current CWD
LINTER_TYPE	Type of linter to use (eslint, golangci-lint)	undefined

Sources: src/config/Config.test.ts:165-220, src/config/Config.test.ts:320-350

Development Environment Setup

For contributors, the project requires Node.js 22+. A devcontainer is provided for a consistent environment. Sources: DEVELOPMENT.md:5-18

Build and Test Sequence

The development workflow follows a strict order to ensure all components and reporters are correctly linked.

Core Commands

• npm run build: Builds the main package and all workspace reporters (Jest, Storybook, Vitest).
• npm run checks: Runs typechecking, linting, formatting, and tests.
• npm run test:reporters: Specifically tests language-specific integration.

Sources: package.json:34-45, CLAUDE.md:82-90

Summary

Setting up TDD Guard involves installing the CLI, integrating a language-specific test reporter to track test states, and configuring Claude Code hooks to trigger validation. This infrastructure ensures that every code modification proposed by the AI is backed by a failing test or a valid refactoring phase, effectively enforcing TDD discipline. Sources: README.md:17-25, CLAUDE.md:5-15