dont-hallucinate 0.1.3

package/README.md

@@ -0,0 +1,154 @@
+# 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

package/bin/dont-hallucinate.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { createCli } from '../src/cli.js';
+
+const program = createCli();
+program.parse(process.argv);

package/dont_hallucinate/hooks/hook.ps1

@@ -0,0 +1,272 @@
+# hallucinate PowerShell hook
+# Dot-source from your profile or from `hallucinate activate --shell powershell`.
+
+if (-not $env:HALLUCINATE_STREAM_FILE -or [string]::IsNullOrWhiteSpace($env:HALLUCINATE_STREAM_FILE)) {
+    $env:HALLUCINATE_STREAM_FILE = Join-Path $env:TEMP "hallucinate_stream.json"
+}
+
+$global:HallucinateSessionId = $PID
+$global:HallucinateLastHistorySignature = ""
+$global:HallucinateLastErrorCount = $Error.Count
+$global:HallucinatePendingCommand = ""
+$global:HallucinatePrevAddToHistoryHandler = $null
+$global:HallucinateEnterHandlerInstalled = $false
+
+if (-not $global:HallucinateOriginalPromptScript) {
+    $promptCmd = Get-Command prompt -ErrorAction SilentlyContinue
+    if ($null -ne $promptCmd -and $promptCmd.ScriptBlock) {
+        $global:HallucinateOriginalPromptScript = $promptCmd.ScriptBlock
+    }
+}
+
+function Invoke-HallucinateHistoryHandler {
+    param(
+        [object]$Handler,
+        [string]$Line
+    )
+
+    if ($null -eq $Handler) {
+        return $true
+    }
+
+    if ($Handler -is [scriptblock]) {
+        return [bool](& $Handler $Line)
+    }
+
+    $invoke = $Handler.PSObject.Methods["Invoke"]
+    if ($null -ne $invoke) {
+        return [bool]($Handler.Invoke($Line))
+    }
+
+    return $true
+}
+
+function Add-HallucinateUtf8Line {
+    param(
+        [string]$Path,
+        [string]$Line
+    )
+
+    $directory = Split-Path -Parent $Path
+    if ($directory) {
+        New-Item -ItemType Directory -Path $directory -Force -ErrorAction SilentlyContinue | Out-Null
+    }
+
+    $encoding = [System.Text.UTF8Encoding]::new($false)
+    $writer = [System.IO.StreamWriter]::new($Path, $true, $encoding)
+    try {
+        $writer.WriteLine($Line)
+    } finally {
+        $writer.Dispose()
+    }
+}
+
+function Install-HallucinatePSReadLineCapture {
+    if ($global:HallucinatePSRLInstalled) {
+        return
+    }
+    Import-Module PSReadLine -ErrorAction SilentlyContinue | Out-Null
+    $setOpt = Get-Command Set-PSReadLineOption -ErrorAction SilentlyContinue
+    if ($null -eq $setOpt) {
+        return
+    }
+
+    try {
+        $opts = Get-PSReadLineOption -ErrorAction SilentlyContinue
+        if ($opts -and $opts.AddToHistoryHandler) {
+            $global:HallucinatePrevAddToHistoryHandler = $opts.AddToHistoryHandler
+        }
+    } catch {
+        $global:HallucinatePrevAddToHistoryHandler = $null
+    }
+
+    try {
+        Set-PSReadLineKeyHandler -Chord Enter -BriefDescription "HallucinateAcceptLine" -ScriptBlock {
+            param($key, $arg)
+            $line = $null
+            $cursor = $null
+            try {
+                [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor)
+            } catch {
+                $line = $null
+            }
+            if (-not [string]::IsNullOrWhiteSpace($line)) {
+                $global:HallucinatePendingCommand = [string]$line
+            }
+            [Microsoft.PowerShell.PSConsoleReadLine]::AcceptLine()
+        }
+        $global:HallucinateEnterHandlerInstalled = $true
+    } catch {
+    }
+
+    try {
+        Set-PSReadLineOption -AddToHistoryHandler {
+            param($line)
+            $allow = $true
+            if ($global:HallucinatePrevAddToHistoryHandler) {
+                try {
+                    $allow = Invoke-HallucinateHistoryHandler -Handler $global:HallucinatePrevAddToHistoryHandler -Line $line
+                } catch {
+                    $allow = $true
+                }
+            }
+            if ($allow) {
+                $global:HallucinatePendingCommand = [string]$line
+            }
+            return $allow
+        }
+        $global:HallucinatePSRLInstalled = $true
+    } catch {
+        if ($global:HallucinateEnterHandlerInstalled) {
+            $global:HallucinatePSRLInstalled = $true
+        }
+    }
+}
+
+function Write-HallucinateDebug {
+    param([string]$Message)
+    if ($env:HALLUCINATE_HOOK_DEBUG -ne "1") {
+        return
+    }
+    $log = Join-Path $env:TEMP "hallucinate_hook_debug.log"
+    Add-HallucinateUtf8Line -Path $log -Line ("{0} {1}" -f (Get-Date).ToString("o"), $Message)
+}
+
+function Test-HallucinatePathUnderRoot {
+    param(
+        [string]$Path,
+        [string]$Root
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Root)) {
+        return $true
+    }
+
+    try {
+        $fullPath = [System.IO.Path]::GetFullPath($Path)
+        $fullRoot = [System.IO.Path]::GetFullPath($Root)
+    } catch {
+        return $false
+    }
+
+    if ($fullPath -eq $fullRoot) {
+        return $true
+    }
+
+    $normalizedRoot = $fullRoot.TrimEnd('\', '/') + [System.IO.Path]::DirectorySeparatorChar
+    return $fullPath.StartsWith($normalizedRoot, [System.StringComparison]::OrdinalIgnoreCase)
+}
+
+function Write-HallucinateEvent {
+    param(
+        [int]$ExitCode,
+        [string]$Command,
+        [string]$StderrText
+    )
+
+    $cwd = (Get-Location).Path
+    if (-not (Test-HallucinatePathUnderRoot -Path $cwd -Root $env:HALLUCINATE_WORKSPACE_ROOT)) {
+        return
+    }
+
+    $payload = [ordered]@{
+        ts             = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+        shell          = "powershell"
+        actor          = $(if ($env:HALLUCINATE_ACTOR) { $env:HALLUCINATE_ACTOR } else { "human" })
+        session        = $global:HallucinateSessionId
+        pid            = $PID
+        cwd            = $cwd
+        workspace_root = $env:HALLUCINATE_WORKSPACE_ROOT
+        exit_code      = $ExitCode
+        command        = $Command
+        stderr         = $StderrText
+    }
+
+    $line = $payload | ConvertTo-Json -Compress
+    Add-HallucinateUtf8Line -Path $env:HALLUCINATE_STREAM_FILE -Line $line
+}
+
+function Get-HallucinateExitCode {
+    param(
+        [bool]$LastSucceeded,
+        [int]$LastNativeExit,
+        [string]$CommandLine
+    )
+
+    $trimmed = if ($CommandLine) { $CommandLine.Trim() } else { "" }
+    $firstToken = if ($trimmed) { ($trimmed -split "\s+")[0].Trim("'`"") } else { "" }
+    $commandInfo = if ($firstToken) { Get-Command $firstToken -ErrorAction SilentlyContinue } else { $null }
+    $isNative = $false
+    if ($null -ne $commandInfo) {
+        $isNative = $commandInfo.CommandType -in @("Application", "ExternalScript")
+    }
+
+    if ($isNative) {
+        if ($null -ne $LastNativeExit) {
+            return [int]$LastNativeExit
+        }
+        return $(if ($LastSucceeded) { 0 } else { 1 })
+    }
+
+    if ($LastSucceeded) {
+        return 0
+    }
+    return 1
+}
+
+function Get-HallucinateRecentErrors {
+    if ($Error.Count -le 0) {
+        $global:HallucinateLastErrorCount = 0
+        return ""
+    }
+
+    $delta = $Error.Count - $global:HallucinateLastErrorCount
+    if ($delta -le 0) {
+        $global:HallucinateLastErrorCount = $Error.Count
+        return ""
+    }
+
+    $upper = [Math]::Min($delta, $Error.Count)
+    $recent = for ($i = 0; $i -lt $upper; $i++) { $Error[$i].ToString() }
+    $global:HallucinateLastErrorCount = $Error.Count
+    return ($recent -join [Environment]::NewLine)
+}
+
+function global:prompt {
+    $lastSucceeded = $?
+    $lastNativeExit = if ($null -eq $global:LASTEXITCODE) { 0 } else { [int]$global:LASTEXITCODE }
+
+    $cmd = ""
+    if (-not [string]::IsNullOrWhiteSpace($global:HallucinatePendingCommand)) {
+        $cmd = [string]$global:HallucinatePendingCommand
+        $global:HallucinatePendingCommand = ""
+    } else {
+        $history = Get-History -Count 1 -ErrorAction SilentlyContinue
+        if ($null -ne $history) {
+            $start = if ($history.StartExecutionTime) { $history.StartExecutionTime.ToUniversalTime().ToString("o") } else { "" }
+            $sig = "{0}|{1}|{2}" -f $history.Id, $start, [string]$history.CommandLine
+            if ($sig -ne $global:HallucinateLastHistorySignature) {
+                $cmd = [string]$history.CommandLine
+                $global:HallucinateLastHistorySignature = $sig
+            }
+        }
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($cmd)) {
+        $exitCode = Get-HallucinateExitCode -LastSucceeded $lastSucceeded -LastNativeExit $lastNativeExit -CommandLine $cmd
+        $stderrText = Get-HallucinateRecentErrors
+        Write-HallucinateDebug ("log cmd=`"{0}`" exit={1} native={2} success={3}" -f $cmd, $exitCode, $lastNativeExit, $lastSucceeded)
+        Write-HallucinateEvent -ExitCode $exitCode -Command $cmd -StderrText $stderrText
+    } else {
+        Write-HallucinateDebug ("skip cmd; pending empty, history unchanged; native={0} success={1}" -f $lastNativeExit, $lastSucceeded)
+    }
+
+    if ($global:HallucinateOriginalPromptScript) {
+        & $global:HallucinateOriginalPromptScript
+    } else {
+        "PS $($executionContext.SessionState.Path.CurrentLocation)> "
+    }
+}
+
+$global:HallucinateHookLoaded = $true
+Install-HallucinatePSReadLineCapture

package/dont_hallucinate/hooks/hook.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+
+if [ -n "${HALLUCINATE_HOOK_LOADED:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+HALLUCINATE_HOOK_LOADED=1
+
+: "${HALLUCINATE_STREAM_FILE:=/tmp/hallucinate_stream.json}"
+
+HALLUCINATE_SESSION_ID="${HALLUCINATE_SESSION_ID:-$$}"
+HALLUCINATE_STATE_FILE="/tmp/hallucinate_state_${HALLUCINATE_SESSION_ID}.target"
+: > "$HALLUCINATE_STATE_FILE"
+
+exec {HALLUCINATE_ORIG_STDERR_FD}>&2
+
+_hallucinate_json_escape() {
+  local s="$1"
+  s=${s//\\/\\\\}
+  s=${s//\"/\\\"}
+  s=${s//$'\n'/\\n}
+  s=${s//$'\r'/\\r}
+  s=${s//$'\t'/\\t}
+  printf '%s' "$s"
+}
+
+_hallucinate_path_within_workspace() {
+  if [ -z "${HALLUCINATE_WORKSPACE_ROOT:-}" ]; then
+    return 0
+  fi
+  case "$PWD/" in
+    "$HALLUCINATE_WORKSPACE_ROOT"/|"$HALLUCINATE_WORKSPACE_ROOT"/*)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+_hallucinate_log_event() {
+  local exit_code="$1"
+  local cmd="$2"
+  local stderr_text="$3"
+  local ts
+  ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  local actor="${HALLUCINATE_ACTOR:-human}"
+
+  _hallucinate_path_within_workspace || return 0
+
+  mkdir -p "$(dirname "$HALLUCINATE_STREAM_FILE")"
+
+  local cmd_esc stderr_esc cwd_esc workspace_esc
+  cmd_esc="$(_hallucinate_json_escape "$cmd")"
+  stderr_esc="$(_hallucinate_json_escape "$stderr_text")"
+  cwd_esc="$(_hallucinate_json_escape "$PWD")"
+  workspace_esc="$(_hallucinate_json_escape "${HALLUCINATE_WORKSPACE_ROOT:-}")"
+
+  printf '{"ts":"%s","shell":"%s","actor":"%s","session":%s,"pid":%s,"cwd":"%s","workspace_root":"%s","exit_code":%s,"command":"%s","stderr":"%s"}\n' \
+    "$ts" "${ZSH_VERSION:+zsh}${BASH_VERSION:+bash}" "$actor" "$HALLUCINATE_SESSION_ID" "$$" "$cwd_esc" "$workspace_esc" "$exit_code" "$cmd_esc" "$stderr_esc" \
+    >> "$HALLUCINATE_STREAM_FILE"
+}
+
+_hallucinate_stderr_router() {
+  local line target
+  while IFS= read -r line || [ -n "$line" ]; do
+    printf '%s\n' "$line" >&"$HALLUCINATE_ORIG_STDERR_FD"
+    target="$(cat "$HALLUCINATE_STATE_FILE" 2>/dev/null)"
+    if [ -n "$target" ]; then
+      printf '%s\n' "$line" >> "$target"
+    fi
+  done
+}
+
+exec 2> >(_hallucinate_stderr_router)
+
+if [ -n "${ZSH_VERSION:-}" ]; then
+  autoload -Uz add-zsh-hook 2>/dev/null || true
+
+  _hallucinate_zsh_preexec() {
+    HALLUCINATE_LAST_CMD="$1"
+    HALLUCINATE_ERR_FILE="/tmp/hallucinate_stderr_${HALLUCINATE_SESSION_ID}.log"
+    : > "$HALLUCINATE_ERR_FILE"
+    printf '%s' "$HALLUCINATE_ERR_FILE" > "$HALLUCINATE_STATE_FILE"
+  }
+
+  _hallucinate_zsh_precmd() {
+    local exit_code="$?"
+    local stderr_text=""
+
+    printf '' > "$HALLUCINATE_STATE_FILE"
+    if [ -n "${HALLUCINATE_ERR_FILE:-}" ] && [ -f "$HALLUCINATE_ERR_FILE" ]; then
+      stderr_text="$(cat "$HALLUCINATE_ERR_FILE")"
+      rm -f "$HALLUCINATE_ERR_FILE"
+    fi
+
+    if [ -n "${HALLUCINATE_LAST_CMD:-}" ]; then
+      _hallucinate_log_event "$exit_code" "$HALLUCINATE_LAST_CMD" "$stderr_text"
+      HALLUCINATE_LAST_CMD=""
+    fi
+  }
+
+  add-zsh-hook preexec _hallucinate_zsh_preexec
+  add-zsh-hook precmd _hallucinate_zsh_precmd
+fi
+
+if [ -n "${BASH_VERSION:-}" ]; then
+  HALLUCINATE_BASH_IN_CMD=0
+  HALLUCINATE_BASH_IN_PROMPT=0
+
+  _hallucinate_bash_preexec() {
+    [ "${HALLUCINATE_BASH_IN_PROMPT:-0}" -eq 1 ] && return 0
+
+    if [ "${HALLUCINATE_BASH_IN_CMD:-0}" -eq 0 ]; then
+      HALLUCINATE_BASH_IN_CMD=1
+      HALLUCINATE_LAST_CMD="$(history 1 | sed 's/^ *[0-9][0-9]* *//')"
+      HALLUCINATE_ERR_FILE="/tmp/hallucinate_stderr_${HALLUCINATE_SESSION_ID}.log"
+      : > "$HALLUCINATE_ERR_FILE"
+      printf '%s' "$HALLUCINATE_ERR_FILE" > "$HALLUCINATE_STATE_FILE"
+    fi
+  }
+
+  _hallucinate_bash_precmd() {
+    local exit_code="$?"
+    local stderr_text=""
+
+    HALLUCINATE_BASH_IN_PROMPT=1
+
+    if [ "${HALLUCINATE_BASH_IN_CMD:-0}" -eq 1 ]; then
+      printf '' > "$HALLUCINATE_STATE_FILE"
+      if [ -n "${HALLUCINATE_ERR_FILE:-}" ] && [ -f "$HALLUCINATE_ERR_FILE" ]; then
+        stderr_text="$(cat "$HALLUCINATE_ERR_FILE")"
+        rm -f "$HALLUCINATE_ERR_FILE"
+      fi
+      _hallucinate_log_event "$exit_code" "${HALLUCINATE_LAST_CMD:-}" "$stderr_text"
+      HALLUCINATE_BASH_IN_CMD=0
+      HALLUCINATE_LAST_CMD=""
+    fi
+
+    HALLUCINATE_BASH_IN_PROMPT=0
+    return "$exit_code"
+  }
+
+  trap '_hallucinate_bash_preexec' DEBUG
+
+  if [ -n "${PROMPT_COMMAND:-}" ]; then
+    PROMPT_COMMAND="_hallucinate_bash_precmd; ${PROMPT_COMMAND}"
+  else
+    PROMPT_COMMAND="_hallucinate_bash_precmd"
+  fi
+fi