Metadata-Version: 2.4
Name: claude-arcade
Version: 0.7.0
Summary: Play games while Claude thinks — a collection of terminal mini-games that hook into Claude Code
Project-URL: Homepage, https://github.com/yourusername/claude-arcade
Project-URL: Issues, https://github.com/yourusername/claude-arcade/issues
License: MIT
Keywords: claude,claude-code,cli,curses,game,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# claude-arcade

Play terminal mini-games while Claude thinks.

Hooks into [Claude Code](https://claude.ai/code) so a game launches automatically every time Claude runs a tool — and disappears the moment it's done. Your terminal is fully restored, nothing is lost.

```
 ████ █      ███  █   █ ███   █████
█     █     █   █ █   █ █  █  █
█     █     █████ █   █ █  █  ████
█     █     █   █ █   █ █  █  █
 ████ █████ █   █  ███  ███   █████

 ███  ████   ████  ███  ███   █████
█   █ █   █ █     █   █ █  █  █
█████ ████  █     █████ █  █  ████
█   █ █ █   █     █   █ █  █  █
█   █ █  █   ████ █   █ ███   █████
```

## Install

```bash
pipx install claude-arcade
```

## Quick start

```bash
# One-time setup — adds hooks to ~/.claude/settings.json
claude-arcade setup

# Use Claude Code as normal
claude

# Bird Hunt launches automatically whenever Claude uses a tool.
# Your terminal is restored when Claude finishes.
```

## Play manually

```bash
claude-arcade play          # open the game menu
claude-arcade play bird     # jump straight into Bird Hunt
claude-arcade play pong     # jump straight into Pong
```

## Games

| Game | Description | Folder |
|------|-------------|--------|
| [Bird Hunt](src/claude_arcade/games/bird/) | Shoot sprite birds flying across the screen | `games/bird/` |
| [Pong](src/claude_arcade/games/pong/) | Classic paddle battle vs the CPU | `games/pong/` |

More games coming — see [Contributing](#contributing) to add your own.

## How it works

`claude-arcade setup` writes three hooks into `~/.claude/settings.json`:

| Hook | Command | Effect |
|------|---------|--------|
| `PreToolUse` | `claude-arcade start` | Launches game on the alternate screen buffer |
| `PostToolUse` | `claude-arcade stop` | Stops game, restores terminal |
| `Stop` | `claude-arcade stop` | Same — catches session end |

The game runs on the [alternate screen buffer](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-The-Alternate-Screen-Buffer) so Claude's output is preserved underneath.

## Remove hooks

```bash
claude-arcade unsetup
```

## Project structure

```
src/claude_arcade/
├── cli.py              entry point
├── splash.py           splash screen + game picker menu
├── setup_hooks.py      Claude Code hook management
├── constants.py        shared runtime constants
└── games/
    ├── bird/
    │   ├── game.py     Bird Hunt logic
    │   └── README.md
    └── pong/
        ├── game.py     Pong logic
        └── README.md
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.

**Quick summary — adding a new game:**

1. Create `src/claude_arcade/games/<name>/`
2. Add `game.py` with a `def <name>_game(stdscr)` function
3. Add `__init__.py` exporting it
4. Add `README.md` for the game
5. Register it in `splash.py` → `GAMES` list and `cli.py` → `_game_fn()`

That's it — no other files need touching.

## Requirements

- macOS or Linux
- Python 3.9+
- Claude Code CLI

## License

MIT
