claude-buddy

claude-buddy

A gacha-rolled ASCII coding companion for Claude Code. Hatch one, name them, and they'll live in the top-right corner of your terminal next to Claude, watching you code and occasionally piping up with personality-driven remarks.

 ╭──────────────────────╮
 │     tests don't      │
 │    lie, but your     │
 │  assumptions do 🦊   │
 ╰──────────────────────╯
            ▼
       /\   /\
      (  \_/  )  /
       \ ^.^ /   \
        > v <     |
       /     \ ~~/
      (_______)

       ★ quine ★
         lvl 3
     ████████░░░░░░░░
    with you 2d 4h

What it does

• Gacha hatch: /buddy hatch --tokens rolls a rarity (common 60% / uncommon 25% / rare 10% / epic 4% / legendary 1%) and a species within that tier. 11 species total.
• Collection economy: hatch tokens unlock on an escalating schedule based on your global level (sum of every buddy's pet level). Token 1 at 5 levels, token 2 at 15, token 3 at 30, token 4 at 50 — each token costs 5 more pet-levels than the last. Rolling a species you already own on --tokens burns the token but grants a duplicate shard; 5 shards can be spent via --shards for a guaranteed new species.
• Skills: every buddy rolls 8 skill stats (wisdom, debugging, refactoring, etc.). Each species has a baseline range and a signature skill that rolls much higher.
• Embedded TUI: claude-buddy launches Claude Code inside a Textual app, with your buddy animated as a floating overlay in the top-right reacting to what you're doing.
• L-shape reflow: Claude's text wraps around the pet's reserved rectangle with word-aware wrapping and paragraph merging, so long prose reflows naturally beside the buddy instead of being cut off. Once Claude's conversation fills past the pet zone, it gets the full terminal width back.
• Hooks: watches UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionStart to shift mood (idle / attentive / watching / sleeping / petted / celebrating).
• Personality-driven speech: your buddy can occasionally pipe up in character via Claude — wise Owlet quotes proverbs, Dragonling snarls at errors, Moonwyrm speaks in cosmic riddles. Uses your existing Claude Code auth (no separate API key).
• Pet your buddy: F1 closes its eyes into a smile, triggers a prrr speech bubble, and ticks up its pets_received counter.
• Talk to your buddy directly: prefix a line with ~{name} (e.g. ~quine what color is the sky) to have your buddy reply instead of Claude.
• Wakes on interaction: a sleeping buddy (idle >120s) wakes back up the moment you prompt Claude or talk to it directly.

Install

Requires Python 3.10+ and the Claude Code CLI (claude) on your PATH.

git clone https://github.com/kpowkitty/claude-buddy.git
cd claude-buddy
./install.sh

The installer:

• creates a venv at buddy/tui/.venv and installs runtime deps,
• copies hook scripts to ~/.claude/buddy/ and merges hook entries into ~/.claude/settings.json,
• symlinks bin/claude-buddy and bin/claude-buddy-hatch into ~/.local/bin/ so you can launch from any directory,
• offers to hatch your first buddy right away.

If ~/.local/bin isn't on your PATH, the installer prints a one-liner to add it.

After installing, restart Claude Code so the hooks take effect — Claude reads ~/.claude/settings.json once at startup, so an already-running session won't see the new hooks. If you skipped the hatch prompt, roll your first buddy with claude-buddy-hatch --tokens (or /buddy hatch --tokens inside Claude).

Usage

Launch the TUI from any terminal:

claude-buddy

Roll a new buddy without opening Claude:

claude-buddy-hatch --tokens   # spend a hatch token (dupes burn it and grant a shard)
claude-buddy-hatch --shards   # spend 5 shards for a guaranteed new species

Claude Code runs full-width; your buddy floats in a reserved rectangle in the top-right corner.

Keybindings (TUI)

All app-level hotkeys are function keys so they never collide with Claude's own bindings.

Key	Action
Ctrl-Q	Quit the app
F1	Pet the active buddy (2-second prrr reaction)
F2	Open the gacha collection menu
F3	Toggle the skill grid
F4	Toggle the buddy panel on/off
F5	Refresh — force Claude to redraw if the view gets corrupted
Scroll wheel	Scroll through the Claude pane's history (pauses the live feed)
Shift-PageUp / Shift-PageDown	Same, via keyboard
Shift-End	Snap back to the live tail
Shift-drag	Select text (handled by your terminal — the app passes the gesture through)
Any keystroke	Resumes live tail if you're scrolled back

Gacha menu (F2)

Opens a modal showing every species you own, grouped by rarity. Arrow keys (or j/k) navigate slots; Enter switches to the highlighted buddy; q or Escape closes. Your active buddy is marked with a star.

Talk to your buddy