idlesnake 0.0.1

Play snake while your CLI thinks

idlesnake

Play snake while your CLI thinks.

idlesnake wraps any command-line tool in a PTY and automatically overlays a snake game when it detects idle time. When the tool starts producing output again, the game instantly stops and shows you the output.

Install

pip install idlesnake

Usage

idlesnake claude                # play snake while Claude thinks
idlesnake ssh prod-server       # play while connecting
idlesnake npm install           # play during dependency resolution

Controls

• Arrow keys or WASD to move the snake
• q to quit the game early (returns to terminal)
• Game starts automatically while the wrapped command is producing output after your input
• Game stops when the command goes quiet (response complete)

Options

idlesnake [OPTIONS] COMMAND [ARGS...]

Options:
  --quiet-threshold SECONDS   Silence that ends a response (default: 3.0)
  --start-grace SECONDS       Sustained output before snake starts (default: 0.3)
  --watchdog-grace SECONDS    Wait for Claude hooks before fallback (default: 10.0)
  --echo-window SECONDS       Echo filter window (default: 0.2)
  --no-hooks                  Skip hook injection for Claude
  --debug                     Write log to /tmp/idlesnake_debug.log
  --version                   Show version
  -h, --help                  Show help

--idle-threshold is kept as a deprecated alias for --quiet-threshold.

How It Works

idlesnake sits between your terminal and the wrapped command using a PTY (pseudoterminal). It uses activity-tracking to decide when the snake is welcome:

1. You type -> direction = "input"
2. Command starts producing output (past the echo window) -> the command is busy -> snake starts after start_grace of sustained output
3. Command keeps producing output (status updates, streaming tokens, tool output) -> snake keeps running
4. Command goes quiet for quiet_threshold -> response is complete -> snake stops, output is revealed

This means the snake runs throughout the busy part of a response — including streaming output — and steps aside cleanly when the command is done.

Claude Code behavior

When the wrapped command is claude (or claude-code), idlesnake first tries signal mode: it writes hook scripts to ~/.local/share/idlesnake/hooks/, generates a temp settings file, and passes it to Claude via --settings. The hooks signal the wrapper on UserPromptSubmit (start snake) and Stop (stop snake), giving precise transitions.

Signal mode is best-effort. Some Claude installs (notably Enterprise-managed) may not invoke hooks declared via --settings. If no hook signal arrives within watchdog_grace seconds of the first child output, idlesnake prints a one-line stderr warning and falls back to activity-tracking for the rest of the session. Pass --no-hooks to skip signal mode entirely.

Troubleshooting: if the snake never appears while Claude is thinking, run idlesnake --debug claude ... and inspect /tmp/idlesnake_debug.log — it records mode selection, signal arrival, and each snake transition with reasons.

Features

• Zero config — no hooks, no settings files, just a prefix command
• Works with any CLI tool
• Pure Python, no dependencies (uses stdlib: curses, pty, select)
• High scores persist across sessions
• Terminal state always restored cleanly on exit

Platform

Unix and macOS only. Requires pty, termios, and curses which are not available on Windows.

Also runs as a module

python -m idlesnake claude