cc-buddy-rehatch

cc-buddy-rehatch is a Bun-first, TypeScript implementation of a Claude Code buddy rehatch tool. It inspects the local Claude Code install, detects the current buddy salt, searches for a salt that produces a chosen appearance, patches the local binary, and clears the companion cache so Claude Code can rehatch the buddy on next launch.

By default, rehatch performs a full refresh: it searches for a new compatible appearance and clears the current buddy soul so Claude Code generates a fresh name and personality on the next /buddy. Use --appearance-only to keep the current soul, or --soul-only to keep the current appearance and refresh just the soul.

This project is based on reverse-engineered community findings, not official Anthropic buddy APIs.

Requirements

• Bun 1.3+ (required at runtime, including npm-installed usage)
• A local Claude Code install
• Claude Code fully closed before patching

Install

Install the published CLI globally with npm:

npm install -g cc-buddy-rehatch

If you are working from a local checkout of this repository instead:

bun install

Usage

If you installed the package globally from npm:

# Interactive rehatch flow
cc-buddy-rehatch rehatch

# Non-interactive rehatch
cc-buddy-rehatch rehatch --species dragon --rarity legendary --eye ✦ --hat wizard --shiny

# Keep the current name/personality and refresh appearance only
cc-buddy-rehatch rehatch --species cat --appearance-only

# Keep the current appearance and refresh name/personality only
cc-buddy-rehatch rehatch --soul-only

# Show the current buddy
cc-buddy-rehatch current

# Inspect the detected Claude Code target
cc-buddy-rehatch inspect

# Run safety checks
cc-buddy-rehatch doctor

# Verify that the current buddy matches a target
cc-buddy-rehatch verify --species dragon --rarity legendary

# Restore the latest backup
cc-buddy-rehatch restore

If you are running from this repository checkout:

# Interactive rehatch flow
bun run src/cli.ts rehatch

# Non-interactive rehatch
bun run src/cli.ts rehatch --species dragon --rarity legendary --eye ✦ --hat wizard --shiny

# Keep the current name/personality and refresh appearance only
bun run src/cli.ts rehatch --species cat --appearance-only

# Keep the current appearance and refresh name/personality only
bun run src/cli.ts rehatch --soul-only

# Show the current buddy
bun run src/cli.ts current

# Inspect the detected Claude Code target
bun run src/cli.ts inspect

# Run safety checks
bun run src/cli.ts doctor

# Verify that the current buddy matches a target
bun run src/cli.ts verify --species dragon --rarity legendary

# Restore the latest backup
bun run src/cli.ts restore

After rehatch or restore, reopen Claude Code and run /buddy if you want Claude Code to regenerate or display the refreshed companion state.

Commands

• rehatch: interactive flow by default; supports --species, --rarity, --eye, --hat, --shiny, --no-shiny, --appearance-only, --soul-only
• current: show the currently detected buddy card
• inspect: print detected paths, fingerprint, salt, and current buddy
• doctor: run install/config/fingerprint/salt compatibility checks
• verify: verify the current buddy against an optional target
• restore: restore the latest backup recorded by the manifest

Common Flags

• --binary-path <path>
• --config-path <path>
• --backup-dir <path>
• --force
• --json
• --verbose
• --no-sign
• --timeout <ms>

Development

bun run typecheck
bun test

Caveats

• This tool patches a local closed-source binary and may break when Claude Code internals change.
• Compatibility is best-effort and marker-based in v1.
• macOS patching may require ad-hoc re-signing.