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