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:

pip install dont-hallucinate

From source:

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

dont-hallucinate install-hook-claude --global

Project-local install:

dont-hallucinate install-hook-claude

Codex CLI

Global install (recommended):

dont-hallucinate install-hook-codex

Project-local install:

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:

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:

~/.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:

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

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:

[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