any-buddy

Claude Code uses a companion system to generate pet visual traits (species, rarity, eyes, hat). This is a deterministic process: it hashes your user ID with a salt string (default: friend-2026-401) and feeds that hash into a Mulberry32 PRNG.

Because the pet is recalculated on every launch based on this hash, you cannot override it via standard configuration files. To get a custom pet, you must change the salt string used in the hashing process.

You can install any-buddy globally via npm or by cloning the repository.

Requirements

• Node.js >= 20
• Bun (Highly recommended for the interactive builder TUI and correct hash computation)
• Claude Code

Platform Support

• Linux: Auto-detects ~/.local/share/claude/versions/
• macOS: Auto-detects and performs ad-hoc re-signing after patching.
• Windows: Works with npm-based installs.

If auto-detection of the Claude Code binary fails, set the CLAUDE_BINARY environment variable to the correct path.

# 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

To ensure your custom pet persists after Claude Code updates, you can install an optional SessionStart hook. This hook runs any-buddy apply --silent at the start of every session. If the binary has been updated (and thus the salt is missing), it re-applies the patch automatically.

This adds the following configuration to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "any-buddy apply --silent"
          }
        ]
      }
    ]
  }
}

Note: The hook adds approximately 50ms of startup time when no patch is required.

To immediately start building or browsing companion pets for Claude Code, use npx to run the latest version without a permanent installation.

If Bun is installed, you will experience the full interactive TUI (Terminal User Interface) with a live ASCII art preview. If Bun is not present, the tool falls back to basic sequential prompts using FNV-1a hashing.

npx any-buddy@latest

The any-buddy project interacts with Claude Code's configuration files to manage companion settings. It searches for configuration in two possible locations within the user's home directory:

1. ~/.claude.json
2. ~/.claude/.config.json

If you are attempting to modify companion settings and encounter errors, ensure you have already run /buddy within Claude Code to 'hatch' a companion, as the configuration keys require a companion object to exist.

The builder state enforces specific rules to ensure valid trait combinations:

1. Rarity/Hat Constraint: If rarity is 'common', the hat must be 'none'. If rarity is not 'common', the hat cannot be 'none' (it defaults to 'crown'). Use applyRarityConstraints to enforce this.
2. Stat Constraint: The dump stat cannot be the same as the peak stat. Use applyDumpConstraint to automatically find the next available StatName if a collision occurs.

When running any-buddy without specific flags, you are presented with a start screen (using either the OpenTUI builder or basic terminal prompts). You can choose from the following actions:

• build: Starts the interactive builder to create a new buddy.
• presets: Opens a browser to select from predefined buddy presets.
• buddies: Manages or views your existing buddies.
• rename: Allows you to change the name of your companion.

If you provide specific trait flags in your command, any-buddy will bypass the interactive start screen and immediately enter the interactive builder mode with those traits applied.

Supported trait flags include:

• --species
• --rarity
• --eye
• --hat
• --preset
• --shiny
• --peak
• --dump

# Example: Bypassing the menu to build a specific species
any-buddy --species "some-species"

If you encounter issues (such as Claude Code failing to launch on macOS due to signing issues) or simply want to remove the companion pet, use the restore command. This patches the salt back to its original value and removes the auto-patch hook. Your saved buddy profiles are not deleted and can be reactivated later using any-buddy buddies.

any-buddy restore