# TDD Guard
[](https://www.npmjs.com/package/tdd-guard)
[](https://pypi.org/project/tdd-guard/)
[](https://github.com/nizos/tdd-guard/actions/workflows/ci.yml)
[](https://github.com/nizos/tdd-guard/actions/workflows/security.yml)
[](LICENSE)
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.
<p align="center">
<a href="https://nizar.se/uploads/videos/tdd-guard-demo.mp4">
<img src="docs/assets/tdd-guard-demo-screenshot.gif" alt="TDD Guard Demo" width="600">
</a>
<br>
<em>Click to watch TDD Guard in action</em>
</p>
## 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
## Installation
Install the TDD Guard CLI globally:
```bash
npm install -g tdd-guard
```
For Python projects, also install the pytest reporter:
```bash
pip install tdd-guard
```
## Quick Start
Getting started is quick and simple:
### 1. 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](docs/quick-commands.md) for `tdd-guard on/off` and [ESLint integration](docs/linting.md) for automated refactoring support.
### 2. Configure Test Reporter
TDD Guard captures test results from your test runner. Ensure your `package.json` or project scripts use the correct test command.
**JavaScript/TypeScript (Vitest)**
Add to `vitest.config.ts`:
```typescript
import { VitestReporter } from 'tdd-guard'
export default defineConfig({
test: {
reporters: ['default', new VitestReporter()],
},
})
```
**Python (pytest)**
No configuration needed - the pytest plugin activates automatically when installed.
## Security Notice
As stated in the [Claude Code Hooks documentation](https://docs.anthropic.com/en/docs/claude-code/hooks#security-considerations):
> 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](https://docs.anthropic.com/en/docs/claude-code/hooks#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](https://github.com/Durafen)
## Learn More
- [Configuration Guide](docs/configuration.md) - Environment variables, model options, and troubleshooting
- [Architecture Decision Records](docs/adr/) - Technical design decisions and rationale
## License
[MIT](LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "tdd-guard",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "tdd, test-driven-development, claude, testing, pytest",
"author": "Nizar Selander",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/49/5b/43f484dab023bbf730c7798841202811f0f417b131704878be3aa5f225ba/tdd_guard-0.5.3.tar.gz",
"platform": null,
"description": "# TDD Guard\n\n[](https://www.npmjs.com/package/tdd-guard)\n[](https://pypi.org/project/tdd-guard/)\n[](https://github.com/nizos/tdd-guard/actions/workflows/ci.yml)\n[](https://github.com/nizos/tdd-guard/actions/workflows/security.yml)\n[](LICENSE)\n\nAutomated TDD enforcement for Claude Code.\n\n## Overview\n\nTDD 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.\n\n<p align=\"center\">\n <a href=\"https://nizar.se/uploads/videos/tdd-guard-demo.mp4\">\n <img src=\"docs/assets/tdd-guard-demo-screenshot.gif\" alt=\"TDD Guard Demo\" width=\"600\">\n </a>\n <br>\n <em>Click to watch TDD Guard in action</em>\n</p>\n\n## Why TDD Guard?\n\n- **Focus on solving problems** - TDD Guard enforces the rules while you design solutions\n- **Save context for what matters** - No more TDD instructions cluttering your CLAUDE.md\n- **Works with your stack** - TypeScript, JavaScript, and Python today. More languages coming soon\n- **Control without context switches** - Toggle with `tdd-guard on/off` mid-session\n- **Flexible validation** - Use local Claude or configure Anthropic API\n\n## Requirements\n\n- Node.js 18+\n- Test Runner:\n - JavaScript/TypeScript: Vitest\n - Python: pytest\n\n## Installation\n\nInstall the TDD Guard CLI globally:\n\n```bash\nnpm install -g tdd-guard\n```\n\nFor Python projects, also install the pytest reporter:\n\n```bash\npip install tdd-guard\n```\n\n## Quick Start\n\nGetting started is quick and simple:\n\n### 1. Configure Claude Code Hook\n\nUse the `/hooks` command in Claude Code:\n\n1. Type `/hooks` in Claude Code\n2. Select `PreToolUse - Before tool execution`\n3. Choose `+ Add new matcher...`\n4. Enter: `Write|Edit|MultiEdit|TodoWrite`\n5. Select `+ Add new hook...`\n6. Enter command: `tdd-guard`\n7. Choose where to save (Project settings recommended)\n\n**Tip:** Also configure [quick commands](docs/quick-commands.md) for `tdd-guard on/off` and [ESLint integration](docs/linting.md) for automated refactoring support.\n\n### 2. Configure Test Reporter\n\nTDD Guard captures test results from your test runner. Ensure your `package.json` or project scripts use the correct test command.\n\n**JavaScript/TypeScript (Vitest)**\n\nAdd to `vitest.config.ts`:\n\n```typescript\nimport { VitestReporter } from 'tdd-guard'\n\nexport default defineConfig({\n test: {\n reporters: ['default', new VitestReporter()],\n },\n})\n```\n\n**Python (pytest)**\n\nNo configuration needed - the pytest plugin activates automatically when installed.\n\n## Security Notice\n\nAs stated in the [Claude Code Hooks documentation](https://docs.anthropic.com/en/docs/claude-code/hooks#security-considerations):\n\n> 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.\n\nWe share this information for transparency. Please read the full [security considerations](https://docs.anthropic.com/en/docs/claude-code/hooks#security-considerations) before using hooks.\n\nTDD 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.\n\n## Known Limitations\n\n- Not tested with multiple subagents in the same project\n\n## Roadmap\n\n- Add support for more testing frameworks (Jest, Mocha, unittest, etc.)\n- Add support for additional programming languages (Go, Rust, Java, etc.)\n- Encourage meaningful refactoring opportunities when tests are green\n- Add support for multiple concurrent subagents per project\n\n## Contributing\n\nContributions are welcome! Feel free to submit issues and pull requests.\n\n**Contributors:**\n\n- Python/pytest support: [@Durafen](https://github.com/Durafen)\n\n## Learn More\n\n- [Configuration Guide](docs/configuration.md) - Environment variables, model options, and troubleshooting\n- [Architecture Decision Records](docs/adr/) - Technical design decisions and rationale\n\n## License\n\n[MIT](LICENSE)\n",
"bugtrack_url": null,
"license": null,
"summary": "Enforces Test-Driven Development principles in Claude Code through automated validation",
"version": "0.5.3",
"project_urls": {
"Bug Tracker": "https://github.com/nizos/tdd-guard/issues",
"Homepage": "https://github.com/nizos/tdd-guard",
"Repository": "https://github.com/nizos/tdd-guard"
},
"split_keywords": [
"tdd",
" test-driven-development",
" claude",
" testing",
" pytest"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "57195cf4e5d908c5e7cf0536f11794e9bfa517e5903c78cdfbb00e98dd8ced1d",
"md5": "979e7257df14b0f019a2bdb0f00ffc84",
"sha256": "13b8acf665d32843534b4c1c8689d9d3984030ede8a2620cbf30c932b7514050"
},
"downloads": -1,
"filename": "tdd_guard-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "979e7257df14b0f019a2bdb0f00ffc84",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6229,
"upload_time": "2025-07-21T11:27:31",
"upload_time_iso_8601": "2025-07-21T11:27:31.289721Z",
"url": "https://files.pythonhosted.org/packages/57/19/5cf4e5d908c5e7cf0536f11794e9bfa517e5903c78cdfbb00e98dd8ced1d/tdd_guard-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "495b43f484dab023bbf730c7798841202811f0f417b131704878be3aa5f225ba",
"md5": "62b53afb826ce30c92312ccfe116cbde",
"sha256": "2da053e50dde5563fdda829a872557ea779f0d7379c3342a1bf4d2c334ad6a35"
},
"downloads": -1,
"filename": "tdd_guard-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "62b53afb826ce30c92312ccfe116cbde",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5891,
"upload_time": "2025-07-21T11:27:32",
"upload_time_iso_8601": "2025-07-21T11:27:32.439878Z",
"url": "https://files.pythonhosted.org/packages/49/5b/43f484dab023bbf730c7798841202811f0f417b131704878be3aa5f225ba/tdd_guard-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 11:27:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nizos",
"github_project": "tdd-guard",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tdd-guard"
}
JSON
