Pick any Claude Code companion pet you want. Choose your species, rarity, eyes, hat, and name.
---
## Quick Start
```bash
npx any-buddy@latest
```
That's it. If Bun is installed, you get the full interactive builder with live preview. Otherwise you'll see sequential prompts with a note to install Bun.
The builder lets you browse species, eyes, rarity, hats, and stats with a live ASCII art preview that updates as you scroll. Navigate with arrow keys, Tab/Enter to advance, Esc to cancel.
## Install
```bash
# npm (global)
npm install -g any-buddy
# or clone
git clone https://github.com/cpaczek/any-buddy.git
cd any-buddy && pnpm install && pnpm link --global
```
### Requirements
- **Node.js >= 20**
- **Bun** -- for the interactive builder TUI and correct hash computation (typically already installed with Claude Code). Without Bun, the tool falls back to basic sequential prompts.
- **Claude Code** -- installed via any standard method
### Platform Support
| Platform | Status | Notes |
|----------|--------|-------|
| Linux | Tested | Auto-detects `~/.local/share/claude/versions/` |
| macOS | Tested | Auto-detects + ad-hoc re-signs after patching |
| Windows | Tested | Works with npm-based installs (`cli.js`) |
> Set `CLAUDE_BINARY=/path/to/binary` if auto-detection fails.
## Usage
```bash
any-buddy # Start screen — build, browse presets, or switch buddies
```
The start screen lets you pick between:
- **Build your own** — full interactive builder with live ASCII preview
- **Browse presets** — 23 curated themed builds with animated preview
- **Saved buddies** — switch between your saved pets (shown when you have saves)
After picking your pet, the entire flow stays in the TUI — salt search with progress bar, naming, personality, patching, and hook setup.
```bash
any-buddy current # Show your current pet
any-buddy preview # Browse without applying
any-buddy apply # Re-apply after Claude Code update
any-buddy restore # Restore original pet
any-buddy buddies # Browse and switch between your buddies
any-buddy rehatch # Delete companion, re-hatch via /buddy
```
### Non-Interactive Mode
Skip prompts with flags (bypasses the start screen):
```bash
any-buddy -s dragon -r legendary -e '✦' -t wizard --shiny --name Draco -y
any-buddy --preset "Arcane Dragon" -y
```
All CLI Flags
| Flag | Short | Description |
|------|-------|-------------|
| `--species ` | `-s` | Species (duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk) |
| `--rarity ` | `-r` | Rarity (common, uncommon, rare, epic, legendary) |
| `--eye ` | `-e` | Eye style (` · ✦ × ◉ @ ° `) |
| `--hat ` | `-t` | Hat (crown, tophat, propeller, halo, wizard, beanie, tinyduck) |
| `--preset ` | | Use a curated preset (e.g., "Arcane Dragon") |
| `--name ` | `-n` | Rename companion |
| `--personality ` | `-p` | Set personality (controls speech bubble) |
| `--shiny` | | Require shiny (~100x longer search) |
| `--peak ` | | Best stat (DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK) |
| `--dump ` | | Worst stat |
| `--yes` | `-y` | Skip confirmations |
| `--no-hook` | | Don't offer auto-patch hook |
| `--silent` | | Suppress output (for hooks) |
## All 18 Species
## Customization Options
## Restoring
```bash
any-buddy restore
```
Patches the salt back to original and removes the auto-patch hook. Your saved buddies are preserved — use `any-buddy buddies` to reactivate one later.
## How It Works
See [HOW_IT_WORKS.md](HOW_IT_WORKS.md) for the full technical deep-dive on hashing, binary patching, the salt search algorithm, and the auto-patch hook.
## Known Limitations
- **macOS**: Binary is ad-hoc re-signed after patching. If Claude Code won't launch, run `any-buddy restore`
- **Bun recommended**: Required for the interactive builder and correct wyhash computation. Without Bun, falls back to sequential prompts with FNV-1a (Node-based installs)
- **Salt dependent**: If Anthropic changes the salt string, the tool will detect this and warn you
- **Stats**: You pick peak/dump stats, but exact values are seed-determined
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
## Credits
- [@jtuskan](https://github.com/jtuskan) -- Windows support for npm-based installs ([#5](https://github.com/cpaczek/any-buddy/pull/5))
- [@aaronepinto](https://github.com/aaronepinto) -- macOS ad-hoc code signing ([#3](https://github.com/cpaczek/any-buddy/pull/3))
- [@joshpocock](https://github.com/joshpocock) -- FNV-1a hash support for Node runtime ([#8](https://github.com/cpaczek/any-buddy/pull/8))
- [@Co-Messi](https://github.com/Co-Messi) -- Multi-worker parallelism + early-exit optimization ([#11](https://github.com/cpaczek/any-buddy/pull/11)), curated preset builds ([#15](https://github.com/cpaczek/any-buddy/pull/15))
- [@Ahmad8864](https://github.com/Ahmad8864) -- 8-core cap idea ([#10](https://github.com/cpaczek/any-buddy/pull/10)), buddy profiles ([#17](https://github.com/cpaczek/any-buddy/pull/17))
## License
[WTFPL](LICENSE) -- Do What The Fuck You Want To Public License.