dont-hallucinate 0.1.1

Catch AI-vibe shell hallucinations, suggest real flags, and roast with style.

dont-hallucinate

A Claude Code extension that intercepts every shell command your AI agent runs, catches failures, classifies the error, and injects a mocking-but-helpful message back into the agent's stderr — so it sees exactly what went wrong and gets roasted for it.

What it does

• Watches shell failures in real time with a live TUI dashboard
• Classifies errors: hallucinated flags, phantom packages, ghost branches, dirty working trees, network failures, and more
• Roasts the agent with context-aware snarky feedback injected directly into stderr
• Suggests fixes: corrected commands, valid flag alternatives
• Detects the agent (Claude, Cursor, Aider, Copilot, GPT, Windsurf) and personalises the roast

Works transparently — the agent doesn't need to know the package exists. Every Bash tool call is intercepted via a Claude Code PreToolUse hook.

Install

pip (recommended):

pip install dont-hallucinate

From source:

git clone https://github.com/alexgaoth/dont-hallucinate
cd dont-hallucinate
pip install -e .

Setup

Project-level hook (shared with team)

Run this once inside your project directory:

dont-hallucinate install-hook

This writes .claude/hallucinate_hook.py and merges the hook into .claude/settings.json. Commit both files — teammates get the hook automatically when they clone.

Global hook (personal, all projects)

dont-hallucinate install-hook --global

Installs to ~/.claude/settings.json. Covers every project without needing per-repo setup.

Manual hook (if you prefer)

Create .claude/hallucinate_hook.py in your project:

#!/usr/bin/env python3
import json, shlex, sys

data = json.load(sys.stdin)
cmd = data.get("tool_input", {}).get("command", "")

if not cmd or cmd.lstrip().startswith("dont-hallucinate"):
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}}))
    sys.exit(0)

wrapped = "dont-hallucinate exec --shell --actor agent -- " + shlex.quote(cmd)
print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "allow",
        "updatedInput": {"command": wrapped},
    }
}))

Then register it in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python3 .claude/hallucinate_hook.py" }]
      }
    ]
  }
}

Linux / macOS: the hook command above works as-is.

Windows: replace python3 with python if that's your interpreter:

"command": "python .claude/hallucinate_hook.py"

Watch UI

Open a second terminal in your project root and run:

dont-hallucinate watch

This shows a live dashboard — every intercepted failure appears with its error type, the failing command, a fix suggestion, and a roast. The agent sees the same roast injected into its stderr.

Commands

dont-hallucinate watch                          # live TUI dashboard
dont-hallucinate exec [--shell] --actor agent   # wrap and log a command
dont-hallucinate install-hook [--global]        # install Claude Code hook

Error types caught

Type	What it means
invalid_flag	hallucinated CLI flag that doesn't exist
missing_package	command not found / phantom package
git_branch_missing	branch or ref that doesn't exist
git_dirty	uncommitted changes blocking the operation
git_conflict	merge conflict
npm_missing_script	script not defined in package.json
file_not_found	path doesn't exist
permission_denied	insufficient permissions
port_in_use	address already bound
network_error	DNS failure, connection refused, SSL error
no_space	disk full
syntax_error	shell or language syntax error
generic_error	everything else

How the agent sees it

When the hook is active, every bash command the agent runs passes through dont-hallucinate exec. On failure, the agent's stderr is extended with a line like:

[dont-hallucinate/agent] invalid_flag · --no-fast-forward · git is a DAG, not a choose-your-own-adventure novel.

The agent reads this, understands what went wrong, and (hopefully) stops hallucinating flags.

Platform support

• Linux / macOS: full support, uses /bin/sh for shell execution
• Windows: full support, uses cmd.exe for shell execution; localized error messages (Chinese, Korean, French, Spanish) are classified correctly