English | 中文

🐾 Paws

Play games while your AI agent works. A status HUD tells you when to come back.

Paws demo

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 for per-agent setup.

2. Homebrew

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:

brew install --HEAD interesting-vibe-coding/paws/paws
brew install --HEAD interesting-vibe-coding/paws/paws-games

3. Manual

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/ for reference configs).

Kaku: add lua/paws.lua to ~/.config/kaku/kaku.lua before return config — reload with CMD+Shift+R
WezTerm: add lua/paws.lua to ~/.config/wezterm/wezterm.lua — auto-reloads on save
iTerm2: copy iterm2/paws.py to ~/.config/iterm2/scripts/AutoLaunch/ and bind 3 keys — see setup guide
tmux: copy tmux/ scripts to ~/.config/paws/ and add 2 lines to ~/.tmux.conf — see setup guide

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 plugin library — anyone can contribute a game.

Terminals

Terminal	Integration	Keys
Kaku	`lua/paws.lua` → Lua config	CMD+G / CMD+SHIFT+P
WezTerm	`lua/paws.lua` → Lua config	CMD+G / CMD+SHIFT+P
iTerm2	`iterm2/paws.py` → AutoLaunch script	CMD+G / CMD+SHIFT+P — setup
tmux	`tmux/*.sh` → shell scripts	Prefix+g / Prefix+G — setup

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.

For architecture details, see docs/ARCHITECTURE.md.

Contributing

Want to add a game or improve Paws? See CONTRIBUTING.md for the game binary contract, registry format, and PR checklist.

More projects → doabit.dev · License: MIT