dont-hallucinate 0.1.0

Catch AI-vibe shell hallucinations, suggest real flags, and roast with style.

hallucinate

hallucinate watches shell failures, suggests safer fixes for bad flags, and roasts the command that failed.

There are three modes:

1. watch Observes a workspace-local JSONL stream at .hallucinate/stream.jsonl.
2. exec / bash Wraps command execution, logs the failure, and appends mocking/helpful feedback to the stderr the agent actually sees.
3. agent-bash via BASH_ENV Lets non-interactive bash processes inherit the hook. This can log failures and append hallucinate feedback when the agent process inherited the environment.

Install

Set-Location E:\hallucinate
C:\Users\HP1\AppData\Local\Programs\Python\Python312\python.exe -m pip install -e .

Fastest Human Workflow

Watcher terminal:

Set-Location E:\your-workspace
hallucinate

Hooked shell terminal:

Set-Location E:\your-workspace
hallucinate shell

That opens a PowerShell session already configured for the current workspace.

Reliable Agent Workflow

If you want the agent to see hallucinate's feedback in the actual command output, wrap the command:

Set-Location E:\your-workspace
hallucinate exec --actor agent bash -lc "fakecommand; ls /bad/path; git merge nonexistentbranch"

Or call the dedicated bash wrapper:

Set-Location E:\your-workspace
hallucinate bash --actor agent -lc "fakecommand; ls /bad/path"

This is the reliable path for agents because hallucinate owns execution and can decorate stderr directly.

Raw Agent Bash Workflow

If an agent launches plain bash processes and inherits your environment, use:

Set-Location E:\your-workspace
Invoke-Expression (& hallucinate activate --shell agent-bash --actor agent)

This exports BASH_ENV, PATH, workspace metadata, and a local bash shim.

What this can do:

• log non-interactive bash failures
• append hallucinate feedback to failing bash stderr
• intercept bash if the agent resolves it from PATH

What this cannot do:

• intercept a bash process launched by an agent that did not inherit these environment variables
• override an agent that uses an execution layer completely outside your current process tree

PATH Bash Shim

hallucinate shell and hallucinate activate ... now create a workspace-local shim at:

.hallucinate/bin/bash

and prepend that directory to PATH.

If an agent resolves bash from PATH, it will hit the shim, which forwards to:

hallucinate bash ...

Important limit:

• This only helps when the agent resolves bash through PATH.
• If the agent hardcodes an absolute bash binary such as /usr/bin/bash, a PATH shim cannot intercept it.
• Absolute-path bash can still be influenced by BASH_ENV, but only if the agent inherited that variable from the activated environment.

Commands

hallucinate
hallucinate shell --actor human|agent
hallucinate exec --actor human|agent <command ...>
hallucinate bash --actor human|agent <bash args ...>
hallucinate activate --shell powershell|bash|agent-bash

What Gets Logged

Each event includes:

• timestamp
• actor (human or agent)
• cwd
• workspace root
• exit code
• command
• stderr

Product Boundary

watch is observational.

exec and bash are intercepting wrappers.

If the goal is "show mocking/helpful feedback directly to the agent", use exec or bash when you can.

Use agent-bash only when the agent insists on launching raw bash but still inherits your environment.