Metadata-Version: 2.4
Name: dont-hallucinate
Version: 0.1.1
Summary: Catch AI-vibe shell hallucinations, suggest real flags, and roast with style.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.7.1
Requires-Dist: rapidfuzz>=3.9.6

# 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):**

```bash
pip install dont-hallucinate
```

**From source:**

```bash
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:

```bash
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)

```bash
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:

```python
#!/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`:

```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:

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

## Watch UI

Open a second terminal in your project root and run:

```bash
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
