WhatTheBash

A passive VS Code companion that explains Claude Code's permission prompts consequence-first, before you approve them. It never blocks or replaces Claude Code's own prompt — it just tells you, in plain terms, what a pending action will do.

How it works

Claude Code's PreToolUse hook POSTs each pending action (a Bash command, an Edit, a Write) to a small HTTP server hosted inside this extension. The extension classifies it into a verdict (safe / caution / destructive) plus concrete consequence flags, and surfaces it on:

• a status bar item — a glanceable, colored verdict of the latest action;
• a history view in the primary sidebar (the eye icon in the activity bar, or click the status bar) — a running list of every action, most recent first, each with its verdict, flags, cautions, and the raw command. Clear it from the view's title bar.

The server always responds passively (HTTP 200, no decision), so your approval flow in Claude Code is untouched. If the extension isn't running, the hook just fails silently and the prompt proceeds as normal.

Develop

Requires Node 24 and VS Code.

npm install      # node_modules is not committed
npm run build    # compiles + bundles to dist/ (not committed)
npm test         # behavior tests

Press F5 to launch an Extension Development Host window with the extension loaded from source.

Install it for real (no F5)

npm run package                          # builds whatthebash.vsix
code --install-extension whatthebash.vsix

Then reload VS Code — it auto-starts in every window. (Don't also run F5 or the standalone server, or you'll get a port-in-use warning: only one can own 4517.)

Test without Claude Code

The extension is just an HTTP listener, so you can drive the UI yourself while the extension (or npm run serve) is running:

npm run demo                       # cycle a sample set, ~2s apart
npm run demo -- "sudo rm -rf /"    # send one custom Bash command

npm run serve runs the same classifier as a standalone terminal server (no editor needed), printing verdict cards to stdout.

Configuration

• whatthebash.port (default 4517) — must match the hook URL in .claude/settings.json.
• whatthebash.token — optional shared secret; if set, the hook must send Authorization: Bearer <token>.

Design notes

See docs/prd.md, docs/tdd.md, the architecture decisions in docs/adr/, and the domain glossary in CONTEXT.md.