🤖 Buddy Battle

PvP Arena Combat for Claude Code Buddies

Buddy Battle brings your Claude Code companion to life in a real-time, turn-based terminal fighting game. Your buddy's species, rarity, and stats are pulled directly from your Claude Code installation — the same little creature that sits beside your prompt is now your champion in the arena.

🎬 Demo

Sharing: docs/demo/demo.mp4 (H.264, best for X and the web). Full-quality capture: docs/demo/recording.mov.

✨ Features

• 🎮 Real-Time PvP — Fight other Claude Code users globally over Supabase Realtime
• 🧬 Deterministic Buddies — Your buddy's species, rarity, and stats are derived from your Anthropic account via Bun.hash
• ⚔️ 4-Move Combat System — Debug Smash, Chaos Bomb, Firewall, and Reboot — each scaled mathematically to your buddy's unique stats
• 💥 Battle Animations — Projectiles fly across the terminal, hits shake the screen
• 🏆 Global Leaderboard — ELO-tracked rankings
• 🔗 X (Twitter) Integration — Brag about your knockout victories directly to X from the terminal
• 🔐 Secure Architecture — Match validation tokens prevent forged wins, and your real Anthropic UUID is SHA-256 hashed to protect your identity.

🚀 Quick Start

Ensure you have Claude Code installed and have hatched a buddy using the /buddy command.

Then just jump right into the arena:

npx -y buddy-battle@latest

Note: For the most accurate buddy stats, ensure Bun is installed on your machine so the client can perfectly match Anthropic's internal hashing algorithm.

🎯 Combat System

Every match is different because every buddy has unique stats! Combat has been completely mathematically balanced to ensure that even a level 100 stat won't instantly one-shot a level 0 buddy, but it will give you a major thematic advantage.

| Move | Stat | Effect | |------|------|--------| | Debug Smash | DEBUGGING | Fast, highly reliable light attack. | | Chaos Bomb | CHAOS | Heavy attack with a high chance to miss. | | Firewall | WISDOM | Defensive block. The higher your wisdom, the larger the percentage of the next incoming hit you block. | | Reboot | PATIENCE | Heals your buddy for a burst of HP. |

🏗️ Technical Architecture

buddy-battle/
├── source/
│   ├── app.tsx              # Root application + state machine
│   ├── cli.tsx              # Entry point
│   ├── extract-bones.ts     # Bun script for accurate stat extraction
│   ├── config/
│   │   └── reader.ts        # Reads ~/.claude.json + shells out to Bun
│   ├── engine/
│   │   ├── types.ts         # Species, rarities, stats
│   │   └── sprites.ts       # ASCII art for all 18 species
│   ├── network/
│   │   └── client.ts        # Supabase RPCs + Match Validators
│   └── ui/
│       ├── Arena.tsx         # Battle screen with animations
│       ├── Matchmaking.tsx   # Lobby + Match Validator Handshake
│       └── ...

Key Security Decisions

• Server-Issued Match Tickets: Clients never exchange claimable win secrets in the lobby. The backend issues one-time match tickets and validates them server-side before ELO updates.
• Session-Scoped RPC Access: Gameplay RPCs require short-lived session assertions and participant checks. Match participants are resolved on the backend, not trusted from client-submitted names/tokens.
• Embedded Client Key with Hardened Backend: The Supabase anon key is embedded for zero-setup UX, but security relies on strict RPC grants, RLS boundaries, and server-side validation logic.

Threat Model Notes

• A player must be signed into Claude Code so their deterministic identity maps to the same profile across devices.
• Debug logging is opt-in only via BUDDY_BATTLE_DEBUG=1; logs redact UUID/JWT-like values to reduce accidental leakage.
• No client-only anti-cheat model is perfect. The backend is authoritative for identity/session/ticket validation, while combat animation exchange remains real-time for responsiveness.

📄 License

MIT