https://github.com/interesting-vibe-coding/paws
๐พ Terminal companion for AI coding agents โ a side-pane game that auto-pauses when your agent needs input
https://github.com/interesting-vibe-coding/paws
Last synced: 25 days ago
JSON representation
๐พ Terminal companion for AI coding agents โ a side-pane game that auto-pauses when your agent needs input
- Host: GitHub
- URL: https://github.com/interesting-vibe-coding/paws
- Owner: interesting-vibe-coding
- License: mit
- Created: 2026-05-31T09:03:58.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-02T16:51:43.000Z (about 1 month ago)
- Last Synced: 2026-06-02T17:12:17.820Z (about 1 month ago)
- Language: Rust
- Size: 144 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
English | [ไธญๆ](README.zh.md)
# ๐พ Paws
[](https://github.com/interesting-vibe-coding/paws/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/interesting-vibe-coding/paws#install) []() [](https://github.com/interesting-vibe-coding/paws/pulls) [](https://github.com/interesting-vibe-coding/paws/stargazers)
Play games while your AI agent works. A status HUD tells you when to come back.
A terminal companion for AI coding agents. Press CMD+G, pick a game, and play in a full-window tab while your agent thinks. A live HUD overlaid on the top row shows which sessions are running and flashes when one finishes โ you switch back when you're ready.
## Use
| Key | Action |
|-----|--------|
| **CMD+G** | First press: open the game picker. After that: toggle agent โ game. |
| **CMD+SHIFT+P** | Re-open the picker to change game. |
| **CMD+H** | Open the Paws repo in your browser. |
The HUD shows session state (running / done) and flashes on completion. No auto-switching โ you stay in control.
## Install
### 1. Let your agent do it (recommended)
> "Install Paws using the skill in `paws/skills/paws-install/SKILL.md`."
Supports **Kiro CLI**, **Claude Code**, and **Codex CLI** โ see the [install skill](skills/paws-install/SKILL.md) for per-agent setup.
### 2. Homebrew
```bash
brew tap interesting-vibe-coding/paws
brew install paws # the paws binary
brew install paws-games # all 7 games
```
Or install the latest development build:
```bash
brew install --HEAD interesting-vibe-coding/paws/paws
brew install --HEAD interesting-vibe-coding/paws/paws-games
```
### 3. Manual
```bash
cargo install --path . # build paws
# Install games individually:
cargo install --git https://github.com/interesting-vibe-coding/paws-games --bin jump-high
cargo install --git https://github.com/interesting-vibe-coding/paws-games --bin earth-online
cargo install --git https://github.com/interesting-vibe-coding/paws-games --bin tetris
cargo install --git https://github.com/interesting-vibe-coding/paws-games --bin snake
cargo install --git https://github.com/interesting-vibe-coding/paws-games --bin 2048
cargo install --git https://github.com/interesting-vibe-coding/paws-games --bin breakout
cargo install --git https://github.com/interesting-vibe-coding/paws-games --bin space-invaders
```
Then wire the terminal integration and hooks for your agent (see [`hooks/`](hooks/) for reference configs).
- **Kaku:** add [`lua/paws.lua`](lua/paws.lua) to `~/.config/kaku/kaku.lua` before `return config` โ reload with CMD+Shift+R
- **WezTerm:** add [`lua/paws.lua`](lua/paws.lua) to `~/.config/wezterm/wezterm.lua` โ auto-reloads on save
- **iTerm2:** copy [`iterm2/paws.py`](iterm2/paws.py) to `~/.config/iterm2/scripts/AutoLaunch/` and bind 3 keys โ see [setup guide](docs/iterm2-setup.md)
- **tmux:** copy [`tmux/`](tmux/) scripts to `~/.config/paws/` and add 2 lines to `~/.tmux.conf` โ see [setup guide](docs/tmux-setup.md)
## Games
| Game | Binary | Description |
|------|--------|-------------|
| ๐ Dog Jump | `jump-high` | Jump King-style platformer โ charge, aim, and pray |
| ๐ Earth Online | `earth-online` | Real-life side quests to run while your agent works |
| ๐งฑ Tetris | `tetris` | Classic block-stacking with levels and scoring |
| ๐พ Space Invaders | `space-invaders` | Classic arcade shooter โ blast the alien fleet before they land |
| ๐ Breakout | `breakout` | Smash bricks with a bouncing ball โ power-ups, hard bricks, 3 lives |
| ๐ Snake | `snake` | Eat, grow, don't bite yourself โ speed scales with score |
| ๐ฎ 2048 | `2048` | Slide tiles, merge numbers, reach 2048 |
Don't see enough? Open **โค Install games** in the picker to browse the catalog and install more in place. The catalog is the [paws-games](https://github.com/interesting-vibe-coding/paws-games) plugin library โ anyone can contribute a game.
## Terminals
| Terminal | Integration | Keys |
|----------|-------------|------|
| [Kaku](https://github.com/tw93/kaku) | `lua/paws.lua` โ Lua config | CMD+G / CMD+SHIFT+P |
| [WezTerm](https://wezfurlong.org/wezterm/) | `lua/paws.lua` โ Lua config | CMD+G / CMD+SHIFT+P |
| [iTerm2](https://iterm2.com) | `iterm2/paws.py` โ AutoLaunch script | CMD+G / CMD+SHIFT+P โ [setup](docs/iterm2-setup.md) |
| tmux | `tmux/*.sh` โ shell scripts | Prefix+g / Prefix+G โ [setup](docs/tmux-setup.md) |
## How it works
Agent hooks write session state to `/tmp/paws-sessions/` โ the terminal integration handles the key binding (spawns/toggles a window) โ the `paws` host runs the chosen game in a PTY and renders the HUD on the top row. Games are standalone binaries discovered via a [registry](registry.toml).
For architecture details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
## Contributing
Want to add a game or improve Paws? See [CONTRIBUTING.md](CONTRIBUTING.md) for the game binary contract, registry format, and PR checklist.
---
More projects โ [doabit.dev](https://doabit.dev) ยท License: MIT