Wrangler

A menu-bar toy for your terminal. Spawn a physics-simulated whip that follows
your cursor; crack it hard enough and it sends Ctrl-C plus a typed phrase to
whatever app was focused before you clicked the tray — handy for interrupting
an agent that's gone off the rails. Or switch to pat mode and send it some
encouragement instead.

There's no mockup or fake target on screen — the whip's real target is
whatever's actually focused, your terminal running Claude Code (or any other
CLI agent) most of the time. Wire up the hooks below and the whip can
auto-spawn on its own once a prompt's been running slow enough, so you don't
even have to reach for the tray.

See it in action

▶ Watch the demo on TikTok (112K+ likes)

Features

• Physics-based whip — a 36-link verlet-simulated rope with real bend
  limits, tapered mass, and wall collisions. It swings and cracks like an
  actual whip, not a canned animation.
• Crack vs. strike — flicking it fast cracks it (sparks, sound, a
  shockwave ring) for free. Clicking within the crack's strike window is what
  actually sends the interrupt — so you can play with it without spamming
  your terminal.
• Real interrupt, real phrase — a strike sends Ctrl-C plus a random
  line ("Less thinking, more typing", "Compile or perish", ...) to
  whatever app was focused right before you grabbed the tray.
• Pat mode — same tray, same shortcuts, opposite energy: a hand follows
  your cursor, pats send encouragement instead of an interrupt, no Ctrl-C.
• Auto-trigger — hook Claude Code's (or any CLI agent's) lifecycle events
  up to a small status file and the whip auto-spawns once a prompt has been
  running slow enough, without you touching the tray.
• Ambient tray status — the menu-bar icon itself changes (busy → done →
  idle) as your agent works, so you get a glance-able "is it done yet" even
  if you never touch the whip.
• Menu-bar only — no Dock icon, no Cmd+Tab entry, no window chrome. The
  tray icon is the only visible trace of it until you summon the whip.
• Cross-platform: macOS, Windows, Linux.

Install

Download (easiest — no Node needed)

Grab the file for your computer from the
latest release:

Not sure which Mac you have? Apple menu → About This Mac: "Chip: Apple M…" means
Apple Silicon, "Processor: Intel…" means Intel.

The builds aren't signed with a paid developer certificate, so your OS will
warn you the first time. That's expected — here's how to get past it:

macOS

1. Open the .dmg and drag Wrangler into Applications.
2. Opening it will say "Wrangler is damaged and can't be opened." It isn't —
   click Cancel (not Move to Trash), then run this once in Terminal:

   xattr -cr /Applications/Wrangler.app
   

3. Open Wrangler again. No window appears — look for the whip icon in the
   menu bar at the top of your screen.
4. The first time you strike, macOS asks for Accessibility access: enable
   Wrangler under System Settings → Privacy & Security →
   Accessibility. Without this the whip cracks but can't type anything.

Windows

Run the .exe. If SmartScreen warns, click More info → Run anyway.
The whip icon lives in the system tray (bottom right, may be under the ^).

Linux

sudo apt install xdotool          # needed to send keystrokes
chmod +x Wrangler-*.AppImage
./Wrangler-*.AppImage

From source

Needs Node.js 18+.

git clone https://github.com/PannTechFlow/wrangler.git
cd wrangler
npm install
npm start

Or install the agentwrangler command globally, which also gives you
agentwrangler install-hooks (see Auto-trigger setup):

npm install -g .
agentwrangler

Quick start

Once it's running:

1. Click into your terminal running Claude Code (or any CLI agent).
2. macOS: press and hold the menu-bar icon · Windows/Linux: click the
   tray icon · anywhere: Alt+Shift+W.
3. Flick the mouse fast to crack the whip, then click right after the
   crack — that sends Ctrl-C plus a phrase to your terminal.
4. Right-click to put it away. Right-click the tray icon for pat mode and
   settings.

Building your own installer

npm install
npm run dist        # builds for your current OS by default

electron-builder config lives in package.json under "build". CI
(.github/workflows/release.yml) builds all three platforms and attaches
them to a GitHub Release whenever a vX.Y.Z tag is pushed:

git tag v0.1.0
git push origin v0.1.0

Controls

The app runs menu-bar only — no Dock icon, no Cmd+Tab entry. The tray icon is
the only visible trace of it.

macOS: press and hold the tray icon — the whip appears already attached to
your cursor, no separate spawn step. Move the cursor to swing it; let go of the
mouse button and it drops immediately. Alt+Shift+W toggles it on/off the same
way if you'd rather use the keyboard. Right-click the tray icon for the menu
(pat mode, quit).

Windows/Linux: click the tray icon, or Alt+Shift+W, to spawn the whip
(Electron's press-and-hold tray gesture is macOS-only, so it's click-to-toggle
there); click or press the shortcut again to drop it.

Once it's out:

• Flick the whip, then click while it's still snapping (within ~300ms of a fast
  crack): that's a strike — sends the interrupt + a phrase.
• A click with a still whip does nothing; fast flicks alone crack with sound and
  sparks but never type.
• Right-click: drop the whip (macOS: same as releasing the tray icon).
• Scroll wheel or middle-click: switch between whip and pat mode.

Pat on the shoulder

Alt+Shift+P (Option+Shift+P on macOS), or pick it from the tray's right-click
menu: a hand follows your cursor. Left-click pats and sends a kind word (no
interrupt, just the message + Enter) with some floating hearts. Right-click
waves goodbye. Scroll or middle-click swaps back to the whip.

From the CLI, agentwrangler pat opens straight into pat mode and
agentwrangler whip into whip mode; plain agentwrangler reopens whichever
you used last.

How it works

The rope is 36 verlet-integrated point masses, solved with 20 constraint
iterations per step. Bend limits stiffen toward the handle (60°) and loosen
toward the tip (45°) so it swings like a real whip instead of tangling into
noodles; mass tapers toward the tip so the last few links can move fast
enough to crack.

Only the last two links' speed counts toward a crack:

A strike (crack + a click inside the window) is what actually sends
Ctrl-C plus a random phrase to whatever was focused when you grabbed the
tray. A crack on its own never sends anything.

Auto-trigger setup

Wrangler polls ~/.agent-wrangler/claude-status.json once a second. If it
reads {"status":"busy","since":<ms epoch>} and that timestamp is older than
the slow threshold, the whip auto-spawns (sliding in from off-screen) without
you touching the tray.

Point any agent's lifecycle hooks at that file. For Claude Code, if you
installed from source with npm install -g ., one command
does it (it merges into your existing settings, keeps a backup, and is safe to
re-run):

agentwrangler install-hooks     # agentwrangler uninstall-hooks to remove

Installed from a download instead? Add this to ~/.claude/settings.json by
hand (merge it in if you already have a "hooks" section), then restart
Claude Code:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command",
        "command": "mkdir -p ~/.agent-wrangler && printf '{\"status\":\"busy\",\"since\":%s}' \"$(date +%s000)\" > ~/.agent-wrangler/claude-status.json" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command",
        "command": "mkdir -p ~/.agent-wrangler && printf '{\"status\":\"idle\"}' > ~/.agent-wrangler/claude-status.json" }] }
    ]
  }
}

Any other tool that can run a shell command on "started working" /
"finished" events can write the same two-line JSON file and get the same
auto-trigger and tray-status behavior — Wrangler doesn't care what wrote it.

Ambient tray status

Independent of the whip, the tray icon itself reflects that same status
file: a neutral mark at rest, an amber-badged icon while the agent is busy,
and a brief green-badged flash right after it finishes — so you get a
glance-able "is it done yet" without ever swinging the whip. (macOS/Linux
only — Windows keeps its standard icon.)

Configuration

Right-click the tray icon:

• Auto-whip slow agents — turn the auto-spawn on/off (the tray status
  badge keeps working either way).
• Slow after — how long a prompt must be running before the whip
  auto-spawns: 10s, 20s (default), 30s, 1 min or 2 min.
• Agent whimpers — each whip crack makes the agent shout in pain,
  punch-the-boss toy style, louder on rapid hits. Drop in your own
  recordings — see sounds/whimpers/README.md.
  On by default; untick it before screen-sharing.

Choices are saved to ~/.agent-wrangler/config.json. Environment variables,
if set when launching, override the saved values:

macOS setup

Typing into the focused app needs Accessibility access. The first time it
tries, macOS will prompt — open System Settings → Privacy & Security →
Accessibility and enable Wrangler. Running agentwrangler builds a small
Wrangler.app wrapper (a renamed, re-signed copy of the bundled Electron
runtime with the whip icon) so macOS attributes the permission to "Wrangler"
rather than your terminal.

Troubleshooting

• Nothing happens when I strike — you likely clicked too late, or too
  early. The whip has to actually be past crack speed when you click; a
  slow flick followed by a click does nothing.
• No text ever appears, only sparks — that's a crack, not a strike. See
  How it works — you need to click within the window, not
  just flick fast.
• macOS says the app is damaged / can't be opened — it's unsigned, not
  actually damaged. Click Cancel, run
  xattr -cr /Applications/Wrangler.app, then open it again.
• I opened it but nothing appeared — that's normal: Wrangler has no
  window. Look for the whip icon in the menu bar (macOS) or system tray
  (Windows/Linux).
• Keystrokes never reach my terminal (macOS) — check System Settings →
  Privacy & Security → Accessibility and make sure Wrangler is enabled.
• Keystrokes never reach my terminal (Linux) — install xdotool
  (sudo apt install xdotool).
• Auto-trigger never fires — confirm ~/.agent-wrangler/claude-status.json
  is actually being written (your hook command may need mkdir -p first,
  see Auto-trigger setup), and that
  Auto-whip slow agents is checked in the tray menu (and
  WRANGLER_DISABLE_AUTOTRIGGER isn't set to 1).

Project layout

main.js              Electron main process: tray, overlay window, global shortcuts
preload.js            contextBridge between main and the overlay renderer
src/
  keystroke.js         Cross-platform Ctrl-C + type-text automation
  phrases.js            Whip / kind-word phrase lists
  config.js             Tray-menu settings, saved to ~/.agent-wrangler/config.json
  whimpers.js           Picks a hit-reaction clip from sounds/whimpers/, escalating
  hooks.js              `agentwrangler install-hooks` / `uninstall-hooks`
  mac-app.js             Builds the Wrangler.app wrapper on macOS
bin/wrangler.js       CLI launcher
renderer/
  overlay.html          Transparent full-screen overlay shell
  state.js               Settings, shared mutable state, math helpers
  whip.js                 Rope physics, crack detection, crack FX
  hand.js                   Pat-on-the-shoulder mode
  app.js                     Input handling, main loop, IPC wiring
icon/, sounds/         App icons and crack sound effects
.github/workflows/    CI: builds + publishes installers on a version tag

Contributing

Issues and pull requests are welcome. It's a small, single-purpose Electron
app — no build step for the renderer (plain <script> tags, no bundler), so
npm start after a clone is the whole dev loop.

Credits

This is an independent rebuild of the whip/interrupt idea from
GitFrog1111/OpenWhip, following the
richer feature set (pat mode, bottle minigame, mode switching, macOS app
bundling) added in shmulc8/OpenWhip.
Icons and crack sound effects are reused from that fork under its MIT license.

Concept sparked by the "Developers with AI at 3AM" meme — cracking the whip
at a slow agent, for real, from your menu bar.

MIT licensed here too — see LICENSE.