Metadata-Version: 2.4
Name: idlesnake
Version: 0.0.1
Summary: Play snake while your CLI thinks
Project-URL: Homepage, https://github.com/b0uks/idlesnake
Author: b0uks
License-Expression: MIT
License-File: LICENSE
Keywords: cli,game,pty,snake,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment :: Arcade
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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

```bash
pip install idlesnake
```

## Usage

```bash
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

```bash
python -m idlesnake claude
```
