# dont-hallucinate

`dont-hallucinate` intercepts agent shell failures, classifies what went wrong, suggests fixes when it can, and mocks your coding agent. By giving a model immediate negative reinforcement helps them to stop foolishly repeating the same mistake.

## 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 snark injected directly into stderr
- Suggests fixes: corrected commands and valid flag alternatives
- Detects the agent (Claude, Cursor, Aider, Copilot, GPT, Windsurf) and personalizes the roast

## Install

Recommended:

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

From source:

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

## Hook Setup

There are now three separate install commands because the integration points are different.

### Claude Code

Global install (recommended):

```bash
dont-hallucinate install-hook-claude --global
```

Project-local install:

```bash
dont-hallucinate install-hook-claude
```

### Codex CLI

Global install (recommended):

```bash
dont-hallucinate install-hook-codex
```

Project-local install:

```bash
dont-hallucinate install-hook-codex --project
```

This updates `~/.codex/config.toml` by default and installs a `shell_environment_policy` block that sets:

- `BASH_ENV` to the noninteractive `dont-hallucinate` bash hook
- `HALLUCINATE_ACTOR=agent`
- `HALLUCINATE_STREAM_FILE=~/.dont-hallucinate/codex/stream.jsonl`

Important scope note:

- This currently covers Codex bash subprocess failures
- It is not a PowerShell-native Codex hook
- If you already use inline `set = {...}` inside `[shell_environment_policy]`, migrate that to `[shell_environment_policy.set]` first

### Cursor

Install the Cursor hook:

```bash
dont-hallucinate install-hook-cursor
```

This appends shell-profile snippets that activate only when Cursor sets `CURSOR_AGENT`.

Files updated:

- PowerShell: `~/Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1`
- Bash: `~/.bashrc`
- Zsh: `~/.zshrc`

The Cursor stream file is written to:

```text
~/.dont-hallucinate/cursor/stream.jsonl
```

Important scope note:

- This is a shell-profile install, not a Cursor settings.json tool hook
- It covers Cursor agent terminal sessions that inherit your normal shell startup files
- Normal terminals are not affected because the snippet checks `CURSOR_AGENT`

## Watch UI

By just running:

```bash
dont-hallucinate
```

It will shows a live dashboard with the failure type, failing command, suggested fix, and roast.
This will work anywhere if global setup. If local setup this will only work in the project root.

## Commands

```text
dont-hallucinate 
dont-hallucinate exec [--shell] --actor agent -- <command>
dont-hallucinate install-hook-claude [--global]
dont-hallucinate install-hook-codex [--project]
dont-hallucinate install-hook-cursor
```

## Error types caught

| Type | What it means |
|---|---|
| `invalid_flag` | hallucinated CLI flag that does not exist |
| `missing_package` | command not found / phantom package |
| `git_branch_missing` | branch or ref that does not 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 does not 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 |

## What the agent sees

When active, the relevant shell command path is wrapped or instrumented so failures are decorated. On failure, stderr gets an extra line like:

```text
[dont-hallucinate/agent] caught: npm run tset
[dont-hallucinate/agent] type: npm_missing_script
[dont-hallucinate/agent] roast: package.json had a menu. GPT ordered something imaginary.
```

## Platform support

- Linux/macOS: fully supported for bash/zsh-based flows
- Windows: supported for PowerShell and bash-based flows
- Codex install currently targets bash subprocess interception
