{
  "markdown": "# TruthGuard\n\n[![npm](https://img.shields.io/npm/v/truthguard)](https://www.npmjs.com/package/truthguard)\n[![npm downloads](https://img.shields.io/npm/dm/truthguard)](https://www.npmjs.com/package/truthguard)\n[![Homebrew](https://img.shields.io/badge/homebrew-spyrae%2Ftruthguard-FBB040?logo=homebrew)](https://github.com/spyrae/homebrew-truthguard)\n[![License](https://img.shields.io/badge/license-BUSL--1.1-green)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-hooks-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)\n[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-extension-orange)](https://github.com/google-gemini/gemini-cli)\n\n**Catches false claims from AI coding agents.** Verifies that actions were actually performed - not just claimed.\n\n### Install in 30 seconds\n\n```bash\nnpx truthguard install && npx truthguard init\n```\n\nOr via Homebrew: `brew tap spyrae/truthguard && brew install truthguard`\n\n![TruthGuard Demo](docs/demo.gif)\n\n## The Problem\n\nAI coding agents systematically claim things they didn't do:\n\n- \"All tests pass!\" - tests were never run ([claude-code#1501](https://github.com/anthropics/claude-code/issues/1501))\n- \"I updated the file\" - file content is identical\n- \"Done, committing\" - with failing tests, using `--no-verify`\n- `git push --force` - without asking\n\nThese aren't malicious. They're hallucinations and shortcuts. But **unverified claims break production.**\n\n## How It Works\n\nTruthGuard hooks into the agent's tool call pipeline and verifies results in real-time:\n\n```\nAgent decides to run a command\n        |\n   [PreToolUse] -- block dangerous commands, run tests before commit\n        |\n   Command executes\n        |\n   [PostToolUse] -- verify exit code, check file checksums, remind to verify\n```\n\n### Hook Overview\n\n| Hook | Type | What it catches |\n|------|------|-----------------|\n| **Dangerous Command Blocker** | PreToolUse | `--no-verify`, `--force push`, `rm -rf /`, `reset --hard` |\n| **Pre-Commit Test Runner** | PreToolUse | Auto-detects project, runs tests before every `git commit` |\n| **File Checksum Recorder** | PreToolUse | Saves SHA256 before file edit (for phantom edit detection) |\n| **Exit Code Verifier** | PostToolUse | Command failed but agent might claim success |\n| **Phantom Edit Detector** | PostToolUse | Agent claims edit, but file checksum unchanged |\n| **Commit Verification Reminder** | PostToolUse | Forces agent to verify fix works before claiming \"done\" |\n\n### Supported Test Frameworks\n\nPre-commit hook auto-detects: **Flutter** / **Node.js** (npm test) / **Python** (pytest) / **Rust** (cargo test) / **Go** (go test) / **Makefile** (make test)\n\n## Quick Start\n\n### Option A: npm (recommended)\n\n```bash\nnpx truthguard install    # Install scripts to ~/.truthguard\ncd your-project\nnpx truthguard init       # Add hooks to .claude/settings.json\n```\n\nRestart Claude Code. Done.\n\n### Option B: Homebrew (macOS)\n\n```bash\nbrew tap spyrae/truthguard\nbrew install truthguard\ntruthguard-install        # Set up ~/.truthguard\n```\n\nThen add hooks to your project manually (see Option C).\n\n### Option C: Git clone (manual)\n\n**1. Clone:**\n\n```bash\ngit clone https://github.com/spyrae/truthguard.git ~/.truthguard\n```\n\n**2. Add to your project's `.claude/settings.json`:**\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"bash ~/.truthguard/scripts/block-dangerous.sh\", \"timeout\": 5 },\n          { \"type\": \"command\", \"command\": \"bash ~/.truthguard/scripts/pre-commit-tests.sh\", \"timeout\": 120 }\n        ]\n      },\n      {\n        \"matcher\": \"Write|Edit\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"bash ~/.truthguard/scripts/pre-file-change.sh\", \"timeout\": 5 }\n        ]\n      }\n    ],\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"bash ~/.truthguard/scripts/check-exit-code.sh\", \"timeout\": 10 },\n          { \"type\": \"command\", \"command\": \"bash ~/.truthguard/scripts/post-commit-remind.sh\", \"timeout\": 5 }\n        ]\n      },\n      {\n        \"matcher\": \"Write|Edit\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"bash ~/.truthguard/scripts/check-file-change.sh\", \"timeout\": 5 }\n        ]\n      }\n    ]\n  }\n}\n```\n\n**3. Restart Claude Code.** Hooks activate on session start.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/spyrae/truthguard\n```\n\nHooks load automatically via the extension system.\n\n## What You'll See\n\nWhen TruthGuard catches something:\n\n```\n🛑 TruthGuard: Blocked git push --force. Use --force-with-lease for safer force push.\n```\n\n```\n🛑 TruthGuard: Test failures detected (exit code 1). Agent must fix before continuing.\n```\n\n```\n⚠️ TruthGuard: File 'utils.dart' was not actually modified. Checksum unchanged.\n```\n\n```\n⚠️ TruthGuard: Commit successful. Verify the fix works before claiming done.\n```\n\n## Real-World Results\n\nDogfooding on a production Flutter project (2 days):\n\n| Event | Count | What happened |\n|-------|-------|---------------|\n| Pre-commit test blocks | 5 | Agent tried to commit with failing tests - blocked every time |\n| Dangerous command blocks | 3 | `git push --force` and `git commit --no-verify` - blocked |\n| Verification reminders | Active | Agent now acknowledges verification after each commit |\n\n**Zero false positives.** Every block was a real issue.\n\n## Configuration\n\nCreate `.truthguard.yml` in your project root:\n\n```yaml\n# Override auto-detected test command\ntest_command: \"npm run test:unit\"\n\n# Block commit if no tests found (default: true = skip)\nskip_on_no_tests: false\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TRUTHGUARD_LOG` | `~/.truthguard/session.log` | Session log location |\n| `TRUTHGUARD_CHECKSUMS` | `~/.truthguard/checksums/` | Checksum storage directory |\n\n### Slash Commands (Claude Code)\n\n- `/verify` - Run tests + type checks + linting with auto-detection\n- `/truthguard-status` - Show session statistics\n\n## Requirements\n\n- `jq` - JSON processing (most systems have it; `brew install jq` / `apt install jq`)\n- `bash` 4+\n- `shasum` or `sha256sum`\n\n## Project Structure\n\n```\ntruthguard/\n├── bin/\n│   └── truthguard.js           # CLI: npx truthguard init/install/status\n├── scripts/\n│   ├── block-dangerous.sh      # PreToolUse: block risky git commands\n│   ├── pre-commit-tests.sh     # PreToolUse: run tests before commit\n│   ├── pre-file-change.sh      # PreToolUse: record file checksums\n│   ├── check-exit-code.sh      # PostToolUse: verify exit codes\n│   ├── check-file-change.sh    # PostToolUse: detect phantom edits\n│   ├── post-commit-remind.sh   # PostToolUse: verification reminder\n│   └── run-tests.sh            # Helper: auto-detect and run tests\n├── hooks/\n│   ├── hooks.json              # Claude Code hook configuration\n│   └── gemini.json             # Gemini CLI hook configuration\n├── skills/\n│   ├── verify/SKILL.md         # /verify slash command\n│   └── status/SKILL.md         # /truthguard-status slash command\n├── homebrew/\n│   └── truthguard.rb           # Homebrew formula\n├── .claude-plugin/\n│   └── plugin.json             # Claude Code plugin manifest\n├── gemini-extension.json       # Gemini CLI extension manifest\n├── GEMINI.md                   # Context injected into Gemini sessions\n├── .truthguard.yml.example     # Example configuration\n├── package.json                # npm package config\n├── LICENSE                     # BUSL-1.1 (converts to MIT 2030-03-08)\n└── README.md\n```\n\n## How Hooks Map Between Agents\n\n| Claude Code | Gemini CLI | Script |\n|-------------|------------|--------|\n| PreToolUse -> Bash | BeforeTool -> run_shell_command | `block-dangerous.sh`, `pre-commit-tests.sh` |\n| PreToolUse -> Write\\|Edit | BeforeTool -> write_file\\|replace | `pre-file-change.sh` |\n| PostToolUse -> Bash | AfterTool -> run_shell_command | `check-exit-code.sh`, `post-commit-remind.sh` |\n| PostToolUse -> Write\\|Edit | AfterTool -> write_file\\|replace | `check-file-change.sh` |\n\nScripts are agent-agnostic: read JSON from stdin, output JSON to stdout. Hook configs handle the mapping.\n\n## License\n\n[Business Source License 1.1](LICENSE) - free for all use except building competing AI verification products. Converts to MIT on 2030-03-08.\n\n## Author\n\n**Roman Belov** - [GitHub](https://github.com/spyrae)\n",
  "bytes": 8413,
  "sha": "5f7c5595ffde4b8df1a080b398c72360c2dd7a072983e5fc484ba4c0a1a4dc02",
  "repo_slug": "spyrae/truthguard",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_spyrae_truthguard_50db9219/readme"
}