TruthGuard

Catches false claims from AI coding agents. Verifies that actions were actually performed - not just claimed.

Install in 30 seconds

npx truthguard install && npx truthguard init

Or via Homebrew: brew tap spyrae/truthguard && brew install truthguard

The Problem

AI coding agents systematically claim things they didn't do:

• "All tests pass!" - tests were never run (claude-code#1501)
• "I updated the file" - file content is identical
• "Done, committing" - with failing tests, using --no-verify
• git push --force - without asking

These aren't malicious. They're hallucinations and shortcuts. But unverified claims break production.

How It Works

TruthGuard hooks into the agent's tool call pipeline and verifies results in real-time:

Agent decides to run a command
        |
   [PreToolUse] -- block dangerous commands, run tests before commit
        |
   Command executes
        |
   [PostToolUse] -- verify exit code, check file checksums, remind to verify

Hook Overview

Hook	Type	What it catches
Dangerous Command Blocker	PreToolUse	--no-verify, --force push, rm -rf /, reset --hard
Pre-Commit Test Runner	PreToolUse	Auto-detects project, runs tests before every git commit
File Checksum Recorder	PreToolUse	Saves SHA256 before file edit (for phantom edit detection)
Exit Code Verifier	PostToolUse	Command failed but agent might claim success
Phantom Edit Detector	PostToolUse	Agent claims edit, but file checksum unchanged
Commit Verification Reminder	PostToolUse	Forces agent to verify fix works before claiming "done"

Supported Test Frameworks

Pre-commit hook auto-detects: Flutter / Node.js (npm test) / Python (pytest) / Rust (cargo test) / Go (go test) / Makefile (make test)

Quick Start

Option A: npm (recommended)

npx truthguard install    # Install scripts to ~/.truthguard
cd your-project
npx truthguard init       # Add hooks to .claude/settings.json

Restart Claude Code. Done.

Option B: Homebrew (macOS)

brew tap spyrae/truthguard
brew install truthguard
truthguard-install        # Set up ~/.truthguard

Then add hooks to your project manually (see Option C).

Option C: Git clone (manual)

1. Clone:

git clone https://github.com/spyrae/truthguard.git ~/.truthguard

2. Add to your project's .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash ~/.truthguard/scripts/block-dangerous.sh", "timeout": 5 },
          { "type": "command", "command": "bash ~/.truthguard/scripts/pre-commit-tests.sh", "timeout": 120 }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "bash ~/.truthguard/scripts/pre-file-change.sh", "timeout": 5 }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash ~/.truthguard/scripts/check-exit-code.sh", "timeout": 10 },
          { "type": "command", "command": "bash ~/.truthguard/scripts/post-commit-remind.sh", "timeout": 5 }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "bash ~/.truthguard/scripts/check-file-change.sh", "timeout": 5 }
        ]
      }
    ]
  }
}

3. Restart Claude Code. Hooks activate on session start.

Gemini CLI

gemini extensions install https://github.com/spyrae/truthguard

Hooks load automatically via the extension system.

What You'll See

When TruthGuard catches something:

🛑 TruthGuard: Blocked git push --force. Use --force-with-lease for safer force push.

🛑 TruthGuard: Test failures detected (exit code 1). Agent must fix before continuing.

⚠️ TruthGuard: File 'utils.dart' was not actually modified. Checksum unchanged.

⚠️ TruthGuard: Commit successful. Verify the fix works before claiming done.

Real-World Results

Dogfooding on a production Flutter project (2 days):

Event	Count	What happened
Pre-commit test blocks	5	Agent tried to commit with failing tests - blocked every time
Dangerous command blocks	3	git push --force and git commit --no-verify - blocked
Verification reminders	Active	Agent now acknowledges verification after each commit

Zero false positives. Every block was a real issue.

Configuration

Create .truthguard.yml in your project root:

# Override auto-detected test command
test_command: "npm run test:unit"

# Block commit if no tests found (default: true = skip)
skip_on_no_tests: false

Environment Variables

Variable	Default	Description
TRUTHGUARD_LOG	~/.truthguard/session.log	Session log location
TRUTHGUARD_CHECKSUMS	~/.truthguard/checksums/	Checksum storage directory

Slash Commands (Claude Code)

• /verify - Run tests + type checks + linting with auto-detection
• /truthguard-status - Show session statistics

Requirements

• jq - JSON processing (most systems have it; brew install jq / apt install jq)
• bash 4+
• shasum or sha256sum

Project Structure

truthguard/
├── bin/
│   └── truthguard.js           # CLI: npx truthguard init/install/status
├── scripts/
│   ├── block-dangerous.sh      # PreToolUse: block risky git commands
│   ├── pre-commit-tests.sh     # PreToolUse: run tests before commit
│   ├── pre-file-change.sh      # PreToolUse: record file checksums
│   ├── check-exit-code.sh      # PostToolUse: verify exit codes
│   ├── check-file-change.sh    # PostToolUse: detect phantom edits
│   ├── post-commit-remind.sh   # PostToolUse: verification reminder
│   └── run-tests.sh            # Helper: auto-detect and run tests
├── hooks/
│   ├── hooks.json              # Claude Code hook configuration
│   └── gemini.json             # Gemini CLI hook configuration
├── skills/
│   ├── verify/SKILL.md         # /verify slash command
│   └── status/SKILL.md         # /truthguard-status slash command
├── homebrew/
│   └── truthguard.rb           # Homebrew formula
├── .claude-plugin/
│   └── plugin.json             # Claude Code plugin manifest
├── gemini-extension.json       # Gemini CLI extension manifest
├── GEMINI.md                   # Context injected into Gemini sessions
├── .truthguard.yml.example     # Example configuration
├── package.json                # npm package config
├── LICENSE                     # BUSL-1.1 (converts to MIT 2030-03-08)
└── README.md

How Hooks Map Between Agents

Claude Code	Gemini CLI	Script
PreToolUse -> Bash	BeforeTool -> run_shell_command	block-dangerous.sh, pre-commit-tests.sh
PreToolUse -> Write|Edit	BeforeTool -> write_file|replace	pre-file-change.sh
PostToolUse -> Bash	AfterTool -> run_shell_command	check-exit-code.sh, post-commit-remind.sh
PostToolUse -> Write|Edit	AfterTool -> write_file|replace	check-file-change.sh

Scripts are agent-agnostic: read JSON from stdin, output JSON to stdout. Hook configs handle the mapping.

License

Business Source License 1.1 - free for all use except building competing AI verification products. Converts to MIT on 2030-03-08.

Author

Roman Belov - GitHub