### Start Any-Buddy Interactive Builder

Source: https://github.com/cpaczek/any-buddy/blob/main/README.md

Launches the Any-Buddy tool, presenting an interactive start screen. If Bun is installed, it opens the full interactive builder with live preview; otherwise, it falls back to sequential prompts.

```bash
npx any-buddy@latest
```

--------------------------------

### Clone and Install Any-Buddy Locally

Source: https://github.com/cpaczek/any-buddy/blob/main/README.md

Clone the any-buddy repository and install dependencies using pnpm. This is useful for development or if you prefer managing local installations.

```bash
git clone https://github.com/cpaczek/any-buddy.git
cd any-buddy && pnpm install && pnpm link --global
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/cpaczek/any-buddy/blob/main/CONTRIBUTING.md

Steps to clone the repository and install project dependencies using pnpm.

```bash
git clone https://github.com/cpaczek/any-buddy.git
cd any-buddy
pnpm install
pnpm run build
```

--------------------------------

### runPreflight(options?)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Validates the environment before patching: checks Bun installation, locates the Claude binary, verifies the salt is present, and handles auto-restore on salt mismatch.

```APIDOC
## runPreflight(options?)

### Description
Validates the environment before patching: checks Bun installation, locates the Claude binary, verifies the salt is present, and handles auto-restore on salt mismatch.

### Parameters
#### Path Parameters
- **options** (object) - Optional - Configuration options.
  - **requireBinary** (boolean) - Optional - If true (default), requires the Claude binary to be found. If false, skips the binary check.

### Request Example
```typescript
import { runPreflight } from './src/patcher/preflight.ts';

const result = runPreflight();

if (!result.ok) {
  process.exit(1);
}

// Skip binary check
const previewResult = runPreflight({ requireBinary: false });
```

### Response
#### Success Response (200)
- **ok** (boolean) - True if the preflight checks passed, false otherwise.
- **binaryPath** (string | null) - The path to the Claude binary if found, otherwise null.
- **userId** (string | null) - The user ID extracted from the binary if found, otherwise null.
- **saltCount** (number | null) - The number of salts found in the binary if applicable, otherwise null.
- **bunVersion** (string | null) - The detected Bun version if Bun is installed, otherwise null.

#### Error Handling
- Errors and warnings are printed directly to the console.
```

--------------------------------

### Install Any-Buddy Globally

Source: https://github.com/cpaczek/any-buddy/blob/main/README.md

Install the any-buddy package globally using npm. This command makes the `any-buddy` executable available system-wide.

```bash
npm install -g any-buddy
```

--------------------------------

### Any-Buddy Non-Interactive Mode with Flags

Source: https://github.com/cpaczek/any-buddy/blob/main/README.md

Use Any-Buddy in non-interactive mode by specifying companion attributes directly via CLI flags. This bypasses the start screen for quick setup.

```bash
any-buddy -s dragon -r legendary -e '✦' -t wizard --shiny --name Draco -y
```

```bash
any-buddy --preset "Arcane Dragon" -y
```

--------------------------------

### Build Specific Pet Non-Interactively

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Builds a specific pet using command-line flags, bypassing the interactive start screen. Use the --yes flag to confirm without prompts.

```bash
any-buddy --species dragon --rarity legendary --eye '✦' --hat wizard --name Draco --yes
```

--------------------------------

### Manage SessionStart Hook

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Installs, removes, or checks the status of the `SessionStart` hook in `~/.claude/settings.json`. This hook auto-patches the binary on Claude Code launch.

```typescript
import { installHook, removeHook, isHookInstalled } from './src/config/hooks.ts';

if (!isHookInstalled()) {
  installHook();
  // Adds to ~/.claude/settings.json:
  // { "hooks": { "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "any-buddy apply --silent" }] }] } }
}

removeHook();
// Removes the any-buddy entry; cleans up empty hooks/SessionStart keys
```

--------------------------------

### Configure Claude Code SessionStart Hook

Source: https://github.com/cpaczek/any-buddy/blob/main/HOW_IT_WORKS.md

Add this JSON configuration to `~/.claude/settings.json` to enable the auto-patch hook. This hook runs `any-buddy apply --silent` on every Claude Code session start.

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

--------------------------------

### Path Alias Imports

Source: https://github.com/cpaczek/any-buddy/blob/main/CONTRIBUTING.md

Example of using path aliases for cross-module imports in TypeScript.

```typescript
import { roll } from '@/generation/roll.js';
```

```typescript
import { SPECIES } from '@/constants.js';
```

--------------------------------

### Same-Directory Imports

Source: https://github.com/cpaczek/any-buddy/blob/main/CONTRIBUTING.md

Example of using relative paths for same-directory imports in TypeScript, which are handled by `rewriteRelativeImportExtensions`.

```typescript
export { roll } from './roll.ts';
```

--------------------------------

### Use Curated Preset Build

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Applies a pet using one of the 23 curated preset builds. The --yes flag confirms the selection.

```bash
any-buddy --preset "Arcane Dragon" --yes
```

--------------------------------

### Dump All Preset Builds

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Outputs all 23 preset builds, including their ASCII sprites, to standard output.

```bash
any-buddy preview --all
```

--------------------------------

### Hook Management

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Manage the `SessionStart` hook in `~/.claude/settings.json` to auto-patch the binary on Claude Code launch.

```APIDOC
## `installHook()` / `removeHook()` / `isHookInstalled()`

### Description
Manage the `SessionStart` hook in `~/.claude/settings.json` that auto-patches the binary on Claude Code launch.

### Usage
```typescript
import { installHook, removeHook, isHookInstalled } from './src/config/hooks.ts';

if (!isHookInstalled()) {
  installHook();
  // Adds to ~/.claude/settings.json:
  // { "hooks": { "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "any-buddy apply --silent" }] }] } }
}

removeHook();
// Removes the any-buddy entry; cleans up empty hooks/SessionStart keys
```
```

--------------------------------

### Run Any-Buddy Commands

Source: https://github.com/cpaczek/any-buddy/blob/main/README.md

Execute various Any-Buddy commands to manage your companion pet. These commands range from viewing the current pet to restoring the original.

```bash
any-buddy                    # Start screen — build, browse presets, or switch buddies
```

```bash
any-buddy current            # Show your current pet
```

```bash
any-buddy preview            # Browse without applying
```

```bash
any-buddy apply              # Re-apply after Claude Code update
```

```bash
any-buddy restore            # Restore original pet
```

```bash
any-buddy buddies            # Browse and switch between your buddies
```

```bash
any-buddy rehatch            # Delete companion, re-hatch via /buddy
```

--------------------------------

### Development Commands

Source: https://github.com/cpaczek/any-buddy/blob/main/CONTRIBUTING.md

Common commands for running and building the project during development.

```bash
pnpm run dev          # Run directly via bun (interactive builder, no build step)
```

```bash
pnpm run dev:build    # Build, then run with bun (test compiled output)
```

```bash
pnpm run dev:node     # Build, then run with node (test fallback prompts)
```

```bash
pnpm run build        # Compile TypeScript + resolve path aliases
```

```bash
pnpm run typecheck    # Type-check without emitting
```

```bash
pnpm run test         # Run all tests
```

```bash
pnpm run test:watch   # Run tests in watch mode
```

```bash
pnpm run lint         # ESLint
```

```bash
pnpm run lint:fix     # ESLint with auto-fix
```

```bash
pnpm run format       # Prettier auto-format
```

```bash
pnpm run format:check # Check formatting
```

--------------------------------

### Require Shiny Pet

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Builds a pet with the 'shiny' attribute enabled. This significantly increases the salt search time.

```bash
any-buddy -s cat -r legendary -e '✦' -t wizard --shiny -y
```

--------------------------------

### Run preflight checks for binary patching

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Validates the environment before patching, including checking for Bun, locating the Claude binary, verifying the salt, and handling automatic restoration if salt mismatches are detected.

```typescript
import { runPreflight } from './src/patcher/preflight.ts';

const result = runPreflight();
// result = {
//   ok: true,
//   binaryPath: '/home/user/.local/bin/claude',
//   userId: 'a1b2c3d4-e5f6-',
//   saltCount: 3,
//   bunVersion: '1.2.4'
// }

if (!result.ok) {
  process.exit(1); // Errors/warnings already printed to console
}

// Skip binary check (e.g., for preview-only operations)
const previewResult = runPreflight({ requireBinary: false });
```

--------------------------------

### Linking CLI Globally

Source: https://github.com/cpaczek/any-buddy/blob/main/CONTRIBUTING.md

Commands to link the CLI globally for direct access and to test the help command.

```bash
pnpm link --global
```

```bash
any-buddy --help
```

--------------------------------

### Submitting Changes

Source: https://github.com/cpaczek/any-buddy/blob/main/CONTRIBUTING.md

Steps to follow when submitting changes, including branching, committing, and opening a pull request.

```bash
git checkout -b my-feature
```

```bash
pnpm run build && pnpm run test && pnpm run lint
```

--------------------------------

### Interactive Pet Preview

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Launches the interactive TUI for browsing pets without modifying the Claude Code binary. Useful for exploring combinations.

```bash
any-buddy preview
```

--------------------------------

### Display Current Pet Details

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Prints the details of the currently active companion pet to standard output. Includes name, species, rarity, eyes, hat, shiny status, and stats.

```bash
any-buddy current
```

--------------------------------

### hashString(s, options?)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Hashes a string using Bun's wyhash (default) or FNV-1a (Node fallback). Results are cached for performance.

```APIDOC
## hashString(s, options?)

### Description
Hashes a string using Bun's wyhash (default) or FNV-1a (Node fallback). Results are cached for performance.

### Parameters
#### Path Parameters
- **s** (string) - Required - The string to hash.
- **options** (object) - Optional - Configuration options.
  - **useNodeHash** (boolean) - Optional - If true, uses FNV-1a via Node.js fallback; otherwise, uses Bun's wyhash.

### Request Example
```typescript
import { hashString } from './src/generation/hash.ts';

// Using Bun wyhash (default)
const h1 = hashString('user-uuid-1234my-custom-salt01');

// Using FNV-1a (Node fallback)
const h2 = hashString('user-uuid-1234my-custom-salt01', { useNodeHash: true });
```

### Response
#### Success Response (200)
- **hash** (number) - A 32-bit unsigned integer representing the hash of the input string.
```

--------------------------------

### Testing Commands

Source: https://github.com/cpaczek/any-buddy/blob/main/CONTRIBUTING.md

Commands for running tests, including watch mode and coverage reports.

```bash
pnpm run test
```

```bash
pnpm run test:watch
```

```bash
pnpm run test:coverage
```

--------------------------------

### findSalt(userId, desired, options?)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Brute-force searches for a 15-character salt that produces the desired pet traits when combined with the user ID. It runs up to 8 parallel workers and resolves with the first match found.

```APIDOC
## findSalt(userId, desired, options?)

### Description
Brute-force searches for a 15-character salt that produces the desired pet traits when combined with the user ID. It runs up to 8 parallel workers and resolves with the first match found.

### Parameters
#### Path Parameters
- **userId** (string) - Required - The user's unique identifier.
- **desired** (DesiredTraits) - Required - An object specifying the desired pet traits.
  - **species** (string) - Required - The desired species of the pet.
  - **rarity** (string) - Required - The desired rarity of the pet.
  - **eye** (string) - Required - The desired eye trait.
  - **hat** (string) - Required - The desired hat trait.
  - **shiny** (boolean) - Required - Whether the pet should be shiny.
  - **peak** (string | null) - Optional - A specific peak trait.
  - **dump** (string | null) - Optional - A specific dump trait.
- **options** (object) - Optional - Configuration options.
  - **onProgress** (function) - Optional - A callback function to report progress.
    - **p** (object) - Progress details.
      - **pct** (number) - Percentage of completion.
      - **attempts** (number) - Number of attempts made.
      - **eta** (number) - Estimated time remaining in seconds.

### Request Example
```typescript
import { findSalt } from './src/finder/index.ts';
import type { DesiredTraits } from './src/types.ts';

const desired: DesiredTraits = {
  species: 'dragon',
  rarity: 'legendary',
  eye: '✦',
  hat: 'wizard',
  shiny: false,
  peak: 'DEBUGGING',
  dump: null,
};

const result = await findSalt('user-uuid-1234', desired, {
  onProgress: (p) => {
    console.log(`${p.pct.toFixed(1)}% — ${p.attempts.toLocaleString()} attempts, ETA ${p.eta.toFixed(0)}s`);
  },
});
```

### Response
#### Success Response (200)
- **salt** (string) - The found 15-character salt.
- **attempts** (number) - The total number of attempts made.
- **elapsed** (number) - The time elapsed in seconds.
- **totalAttempts** (number) - The total possible attempts.
- **workers** (number) - The number of workers used.
```

--------------------------------

### Restore binary from backup

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Restores the original binary file from its `.anybuddy-bak` backup, which was created by `patchBinary`. This operation will fail if no backup exists.

```typescript
import { restoreBinary } from './src/patcher/patch.ts';

restoreBinary('/home/user/.local/bin/claude');
// Copies <binaryPath>.anybuddy-bak → <binaryPath> atomically
// Throws if no backup exists
// Returns true on success
```

--------------------------------

### Access Curated Themed Preset Builds

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Provides access to predefined companion builds. Use `PRESETS.find` to retrieve a specific preset by name or `PRESETS.map` to list all available preset names. Presets can be converted to `DesiredTraits` for further use.

```typescript
import { PRESETS } from './src/presets.ts';
import type { Preset } from './src/presets.ts';

// Find a preset by name
const arcane = PRESETS.find((p: Preset) => p.name === 'Arcane Dragon');
// → { name: 'Arcane Dragon', description: 'A legendary wizard dragon with starry eyes',
//      species: 'dragon', rarity: 'legendary', eye: '✦', hat: 'wizard' }

// List all preset names
const names = PRESETS.map((p) => p.name);
// ['Arcane Dragon', 'Dragon King', 'Cozy Cat', 'Witch Cat', 'Royal Capybara', ...]

// Convert preset to DesiredTraits for findSalt()
const desired = { ...arcane, shiny: false, peak: null, dump: null };
```

--------------------------------

### Salt Operations

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Inspect the Claude binary to read the current salt and verify expected salt presence. Includes low-level buffer scanning.

```APIDOC
## `getCurrentSalt(binaryPath)` / `verifySalt(binaryPath, salt)`

### Description
Inspect the Claude binary to read the current salt and verify expected salt presence.

### Usage
```typescript
import { getCurrentSalt, verifySalt, findAllOccurrences } from './src/patcher/salt-ops.ts';

const state = getCurrentSalt('/home/user/.local/bin/claude');
// state = { salt: 'friend-2026-401', patched: false, offsets: [1042388, 5821044, 9341200] }
// If patched: { salt: null, patched: true, offsets: [] }

const check = verifySalt('/home/user/.local/bin/claude', 'aB3xK9mNpQrSt7u');
// check = { found: 3, offsets: [1042388, 5821044, 9341200] }

// Low-level buffer scan
const buf = readFileSync('/home/user/.local/bin/claude');
const offsets = findAllOccurrences(buf, 'friend-2026-401');
// → [1042388, 5821044, 9341200]
```
```

--------------------------------

### Hash strings with Bun's wyhash or FNV-1a

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Hashes strings using Bun's wyhash by default, with an option to use Node.js's FNV-1a fallback. Results are cached internally.

```typescript
import { hashString, fnv1a } from './src/generation/hash.ts';

// Bun wyhash (matches compiled Claude Code binary on Linux/macOS)
const h1 = hashString('user-uuid-1234my-custom-salt01');
// → 32-bit unsigned integer, e.g. 2847392011

// FNV-1a (matches npm-installed Claude Code on Windows)
const h2 = hashString('user-uuid-1234my-custom-salt01', { useNodeHash: true });

// Direct FNV-1a without subprocess
const h3 = fnv1a('any string'); // → 32-bit unsigned integer
```

--------------------------------

### Profile Management for Any-Buddy

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Handles saving, loading, switching, and deleting buddy profiles. Profiles are stored in `~/.claude-code-any-buddy.json` and include details like salt, species, and stats.

```typescript
import {
  loadPetConfigV2, savePetConfigV2,
  saveProfile, getProfiles,
  switchToProfile, deleteProfile,
} from './src/config/pet-config.ts';
import type { ProfileData } from './src/types.ts';

// Save a new profile
const profile: ProfileData = {
  salt: 'aB3xK9mNpQrSt7u',
  species: 'dragon', rarity: 'legendary', eye: '✦', hat: 'wizard',
  shiny: false, stats: { DEBUGGING: 97, PATIENCE: 52, CHAOS: 61, WISDOM: 83, SNARK: 44 },
  name: 'Draco', personality: null, createdAt: new Date().toISOString(),
};
saveProfile(profile, { activate: true }); // saves and sets as active

// List all saved profiles (keyed by salt)
const profiles = getProfiles();
// { 'aB3xK9mNpQrSt7u': { species: 'dragon', name: 'Draco', ... } }

// Switch active profile (updates config.salt to trigger re-patch on next apply)
const config = switchToProfile('aB3xK9mNpQrSt7u');

// Delete a non-active profile
deleteProfile('xZ7mKqWpNrLtVbY');
// Throws if the profile is currently active
```

--------------------------------

### Profile Management

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Save, load, switch, and delete buddy profiles stored in `~/.claude-code-any-buddy.json`.

```APIDOC
## Profile Management

### Description
Save, load, switch, and delete buddy profiles stored in `~/.claude-code-any-buddy.json`.

### Functions
- `loadPetConfigV2()`
- `savePetConfigV2()`
- `saveProfile(profile: ProfileData, options?: { activate?: boolean })`
- `getProfiles()`
- `switchToProfile(salt: string)`
- `deleteProfile(salt: string)`

### Usage
```typescript
import {
  loadPetConfigV2, savePetConfigV2,
  saveProfile, getProfiles,
  switchToProfile, deleteProfile,
} from './src/config/pet-config.ts';
import type { ProfileData } from './src/types.ts';

// Save a new profile
const profile: ProfileData = {
  salt: 'aB3xK9mNpQrSt7u',
  species: 'dragon', rarity: 'legendary', eye: '✦', hat: 'wizard',
  shiny: false, stats: { DEBUGGING: 97, PATIENCE: 52, CHAOS: 61, WISDOM: 83, SNARK: 44 },
  name: 'Draco', personality: null, createdAt: new Date().toISOString(),
};
saveProfile(profile, { activate: true }); // saves and sets as active

// List all saved profiles (keyed by salt)
const profiles = getProfiles();
// { 'aB3xK9mNpQrSt7u': { species: 'dragon', name: 'Draco', ... } }

// Switch active profile (updates config.salt to trigger re-patch on next apply)
const config = switchToProfile('aB3xK9mNpQrSt7u');

// Delete a non-active profile
deleteProfile('xZ7mKqWpNrLtVbY');
// Throws if the profile is currently active
```
```

--------------------------------

### patchBinary(binaryPath, oldSalt, newSalt)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Atomically patches all occurrences of `oldSalt` in the Claude Code binary with `newSalt`. Both salts must be exactly 15 characters. Creates a `.anybuddy-bak` backup before the first patch.

```APIDOC
## patchBinary(binaryPath, oldSalt, newSalt)

### Description
Atomically patches all occurrences of `oldSalt` in the Claude Code binary with `newSalt`. Both salts must be exactly 15 characters. Creates a `.anybuddy-bak` backup before the first patch.

### Parameters
#### Path Parameters
- **binaryPath** (string) - Required - The path to the Claude Code binary file.
- **oldSalt** (string) - Required - The original 15-character salt to be replaced.
- **newSalt** (string) - Required - The new 15-character salt to replace with.

### Request Example
```typescript
import { patchBinary } from './src/patcher/patch.ts';

const result = patchBinary(
  '/home/user/.local/bin/claude',
  'friend-2026-401',        // original salt (always 15 chars)
  'aB3xK9mNpQrSt7u',       // found by findSalt()
);
```

### Response
#### Success Response (200)
- **replacements** (number) - The number of occurrences of `oldSalt` that were patched.
- **verified** (boolean) - True if the binary was re-read and the `newSalt` is confirmed to be present.
- **backupPath** (string) - The path to the created backup file.
- **codesigned** (boolean) - True if the binary was re-signed (macOS only).
- **codesignError** (string | null) - An error message if code signing failed, otherwise null.
```

--------------------------------

### Share Current Pet

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Generates an ASCII art card of the current pet and copies it to the system clipboard for sharing.

```bash
any-buddy share
```

--------------------------------

### Find a 15-character salt for desired pet traits

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Performs a brute-force search for a 15-character salt that, when combined with a user ID, produces specific pet traits. It utilizes up to 8 parallel workers and reports progress.

```typescript
import { findSalt } from './src/finder/index.ts';
import type { DesiredTraits } from './src/types.ts';

const desired: DesiredTraits = {
  species: 'dragon',
  rarity: 'legendary',
  eye: '✦',
  hat: 'wizard',
  shiny: false,
  peak: 'DEBUGGING',
  dump: null,
};

const result = await findSalt('user-uuid-1234', desired, {
  onProgress: (p) => {
    console.log(`${p.pct.toFixed(1)}% — ${p.attempts.toLocaleString()} attempts, ETA ${p.eta.toFixed(0)}s`);
  },
});
// result = { salt: 'aB3xK9mNpQrSt7u', attempts: 94213, elapsed: 1840, totalAttempts: 712048, workers: 8 }
```

--------------------------------

### mulberry32(seed)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Creates a deterministic Mulberry32 PRNG function from a 32-bit integer seed. The returned function generates a sequence of pseudo-random numbers.

```APIDOC
## mulberry32(seed)

### Description
Creates a deterministic Mulberry32 PRNG function from a 32-bit integer seed. The returned function generates a sequence of pseudo-random numbers.

### Parameters
#### Path Parameters
- **seed** (number) - Required - A 32-bit integer to seed the PRNG.

### Request Example
```typescript
import { mulberry32 } from './src/generation/rng.ts';

const rng = mulberry32(12345678);
console.log(rng()); // 0.2341...
console.log(rng()); // 0.8821...
```

### Response
#### Success Response (Function)
A function that returns a pseudo-random number between 0 and 1 when called.

#### Response Example
```javascript
() => number
```
```

--------------------------------

### Render ASCII Art Sprites with Animation and Hats

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Renders sprites for pet traits, supporting static and animated frames, sleeping states, and hat application. Ensure the correct `Bones` type and frame index are provided.

```typescript
import { renderSprite, renderAnimatedSprite, renderFace, spriteFrameCount } from './src/sprites/render.ts';
import type { Bones } from './src/types.ts';

const bones: Bones = {
  species: 'dragon', rarity: 'legendary', eye: '✦', hat: 'wizard', shiny: false, stats: {}
};

// Static frame (frame 0, awake)
const lines = renderSprite(bones, 0, false);
// → ['  /\', ' /✦~✦\', ' -----', ...]  (hat applied to line[0] if present)

// Sleeping frame (eyes replaced with '-')
const sleeping = renderSprite(bones, 0, true);

// Animated frame from the 15-step IDLE_SEQUENCE
// IDLE_SEQUENCE = [0,0,0,0,1,0,0,0,-1,0,0,2,0,0,0] (-1 = sleeping)
const animated = renderAnimatedSprite(bones, 8); // frame 8 → sleeping
const animated2 = renderAnimatedSprite(bones, 4, 6); // frame 4, padded to 6 lines height

// Face-only string for inline display
const face = renderFace({ species: 'dragon', eye: '✦' }); // → '<✦~✦>'

// Number of animation frames for a species
const frames = spriteFrameCount('dragon'); // → 3
```

--------------------------------

### Binary Detection

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Automatically detect the Claude Code binary or Bun binary path. Supports environment variable overrides.

```APIDOC
## `findClaudeBinary()` / `findBunBinary()`

### Description
Auto-detect the Claude Code binary or Bun binary path. Respects the `CLAUDE_BINARY` environment variable override.

### Usage
```typescript
import { findClaudeBinary, findBunBinary } from './src/patcher/binary-finder.ts';

// Auto-detect Claude binary (checks PATH, platform-specific locations)
// Override with: CLAUDE_BINARY=/path/to/binary
const claudePath = findClaudeBinary();
// Linux:   ~/.local/share/claude/versions/<ver>/claude
// macOS:   ~/.claude/local/claude or /opt/homebrew/bin/claude
// Windows: %LOCALAPPDATA%\Programs\claude\claude.exe or npm cli.js

const bunPath = findBunBinary();
// Checks PATH, then ~/.bun/bin/bun, /usr/local/bin/bun, ~/.volta/bin/bun
```
```

--------------------------------

### Create and use a Mulberry32 PRNG

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Generates a deterministic pseudo-random number generator from a seed. Use this for reproducible random sequences.

```typescript
import { mulberry32, pick } from './src/generation/rng.ts';

const rng = mulberry32(12345678);
console.log(rng()); // 0.2341... (always the same for seed 12345678)
console.log(rng()); // 0.8821... (next value in sequence)

// pick() selects a random element from a readonly array using the RNG
const SPECIES = ['duck', 'cat', 'dragon'] as const;
const chosen = pick(rng, SPECIES); // deterministic pick
```

--------------------------------

### fnv1a(s)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Directly computes the FNV-1a hash of a string. This is a fallback for environments without Bun.

```APIDOC
## fnv1a(s)

### Description
Directly computes the FNV-1a hash of a string. This is a fallback for environments without Bun.

### Parameters
#### Path Parameters
- **s** (string) - Required - The string to hash.

### Request Example
```typescript
import { fnv1a } from './src/generation/hash.ts';

const h3 = fnv1a('any string');
```

### Response
#### Success Response (200)
- **hash** (number) - A 32-bit unsigned integer representing the FNV-1a hash of the input string.
```

--------------------------------

### Patch binary with a new salt

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Atomically replaces all occurrences of an old 15-character salt with a new one in a specified binary file. It creates a backup before patching.

```typescript
import { patchBinary } from './src/patcher/patch.ts';

const result = patchBinary(
  '/home/user/.local/bin/claude',
  'friend-2026-401',        // original salt (always 15 chars)
  'aB3xK9mNpQrSt7u',       // found by findSalt()
);
// result = {
//   replacements: 3,         // number of occurrences patched
//   verified: true,          // re-read confirms new salt is present
//   backupPath: '/home/user/.local/bin/claude.anybuddy-bak',
//   codesigned: false,       // true on macOS after ad-hoc re-signing
//   codesignError: null
// }
```

--------------------------------

### Generate Pet Traits from User ID and Salt

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Deterministically generates pet traits (species, rarity, eyes, hat, stats) using a user ID and a salt string. This function mirrors Claude Code's internal logic. An option `useNodeHash` is available for Node.js compatibility on Windows.

```typescript
import { roll } from './src/generation/roll.ts';

const result = roll('user-uuid-1234', 'friend-2026-401');
// result.bones = {
//   species: 'duck',
//   rarity: 'common',
//   eye: '·',
//   hat: 'none',
//   shiny: false,
//   stats: { DEBUGGING: 12, PATIENCE: 18, CHAOS: 9, WISDOM: 14, SNARK: 7 }
// }
// result.inspirationSeed = 482910341

// Force Node-compatible FNV-1a hash (for npm-installed Claude on Windows)
const nodeResult = roll('user-uuid-1234', 'my-custom-salt01', { useNodeHash: true });
```

--------------------------------

### Browse and Switch Saved Buddies

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Opens an interactive TUI gallery to browse and switch between saved buddy profiles. Selecting a profile activates it.

```bash
any-buddy buddies
```

--------------------------------

### restoreBinary(binaryPath)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Restores the original Claude Code binary from the backup created by `patchBinary`.

```APIDOC
## restoreBinary(binaryPath)

### Description
Restores the original Claude Code binary from the backup created by `patchBinary`.

### Parameters
#### Path Parameters
- **binaryPath** (string) - Required - The path to the Claude Code binary file to restore.

### Request Example
```typescript
import { restoreBinary } from './src/patcher/patch.ts';

restoreBinary('/home/user/.local/bin/claude');
```

### Response
#### Success Response (200)
- **success** (boolean) - True if the restoration was successful. The operation is atomic.

#### Error Handling
- Throws an error if no backup file exists for the specified `binaryPath`.
```

--------------------------------

### Re-hatch New Companion

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Deletes the current companion from `~/.claude.json`, forcing Claude Code to generate a new one via `/buddy`. This does not restore the binary patch.

```bash
any-buddy rehatch
```

--------------------------------

### Find Claude or Bun Binary Path

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Automatically detects the path to the Claude Code binary or Bun binary. It respects the CLAUDE_BINARY environment variable for overrides. Different operating systems have different default locations.

```typescript
import { findClaudeBinary, findBunBinary } from './src/patcher/binary-finder.ts';

// Auto-detect Claude binary (checks PATH, platform-specific locations)
// Override with: CLAUDE_BINARY=/path/to/binary
const claudePath = findClaudeBinary();
// Linux:   ~/.local/share/claude/versions/<ver>/claude
// macOS:   ~/.claude/local/claude or /opt/homebrew/bin/claude
// Windows: %LOCALAPPDATA%\Programs\claude\claude.exe or npm cli.js

const bunPath = findBunBinary();
// Checks PATH, then ~/.bun/bin/bun, /usr/local/bin/bun, ~/.volta/bin/bun
```

--------------------------------

### Inspect and Verify Claude Binary Salt

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Reads the current salt from the Claude binary and verifies if an expected salt is present. Includes a low-level function to find all occurrences of a salt within a buffer.

```typescript
import { getCurrentSalt, verifySalt, findAllOccurrences } from './src/patcher/salt-ops.ts';

const state = getCurrentSalt('/home/user/.local/bin/claude');
// state = { salt: 'friend-2026-401', patched: false, offsets: [1042388, 5821044, 9341200] }
// If patched: { salt: null, patched: true, offsets: [] }

const check = verifySalt('/home/user/.local/bin/claude', 'aB3xK9mNpQrSt7u');
// check = { found: 3, offsets: [1042388, 5821044, 9341200] }

// Low-level buffer scan
const buf = readFileSync('/home/user/.local/bin/claude');
const offsets = findAllOccurrences(buf, 'friend-2026-401');
// → [1042388, 5821044, 9341200]
```

--------------------------------

### Restore Original Claude Code Pet

Source: https://github.com/cpaczek/any-buddy/blob/main/README.md

Reverts the Claude Code companion pet to its original state by patching the salt back and removing the auto-patch hook. Saved buddies remain accessible.

```bash
any-buddy restore
```

--------------------------------

### Companion Name and Personality Management

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Reads and writes companion metadata such as user ID, name, and personality. This data is stored in `~/.claude.json` or `~/.claude/.config.json`.

```typescript
import {
  getClaudeUserId,
  getCompanionName, renameCompanion,
  getCompanionPersonality, setCompanionPersonality,
  deleteCompanion,
} from './src/config/claude-config.ts';

const userId = getClaudeUserId();
// → 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' (from oauthAccount.accountUuid or userID)
// → 'anon' if ~/.claude.json doesn't exist or has no ID

const name = getCompanionName(); // → 'Draco' | null
renameCompanion('Smaug');        // writes config.companion.name

const p = getCompanionPersonality(); // → 'A fierce guardian...' | null
setCompanionPersonality('Prefers tabs over spaces and is not shy about it.');

deleteCompanion(); // removes config.companion entirely (triggers re-hatch via /buddy)
```

--------------------------------

### Re-apply Saved Pet

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Re-applies the saved pet configuration after a Claude Code update. The --silent flag is used by the SessionStart hook to suppress output.

```bash
any-buddy apply
```

```bash
any-buddy apply --silent
```

```bash
any-buddy apply --no-hook
```

--------------------------------

### Estimate salt search attempts

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Calculates the expected number of attempts required to find a salt for a given set of desired pet traits based on probability.

```typescript
import { estimateAttempts } from './src/finder/estimator.ts';

estimateAttempts({ species: 'duck', rarity: 'common', eye: '·', hat: 'none', shiny: false, peak: null, dump: null });
// → 180

estimateAttempts({ species: 'dragon', rarity: 'legendary', eye: '✦', hat: 'wizard', shiny: false, peak: null, dump: null });
// → 86400

estimateAttempts({ species: 'cat', rarity: 'legendary', eye: '✦', hat: 'wizard', shiny: true, peak: 'WISDOM', dump: 'SNARK' });
// → 172800000  (~3 minutes at full parallelism)
```

--------------------------------

### Companion Metadata

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Read and write companion metadata (name, personality) in `~/.claude.json`.

```APIDOC
## Companion Metadata

### Description
Read and write companion metadata in `~/.claude.json` (or `~/.claude/.config.json`).

### Functions
- `getClaudeUserId()`
- `getCompanionName()`
- `renameCompanion(name: string)`
- `getCompanionPersonality()`
- `setCompanionPersonality(personality: string)`
- `deleteCompanion()`

### Usage
```typescript
import {
  getClaudeUserId,
  getCompanionName, renameCompanion,
  getCompanionPersonality, setCompanionPersonality,
  deleteCompanion,
} from './src/config/claude-config.ts';

const userId = getClaudeUserId();
// → 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' (from oauthAccount.accountUuid or userID)
// → 'anon' if ~/.claude.json doesn't exist or has no ID

const name = getCompanionName(); // → 'Draco' | null
renameCompanion('Smaug');        // writes config.companion.name

const p = getCompanionPersonality(); // → 'A fierce guardian...' | null
setCompanionPersonality('Prefers tabs over spaces and is not shy about it.');

deleteCompanion(); // removes config.companion entirely (triggers re-hatch via /buddy)
```
```

--------------------------------

### estimateAttempts(desired)

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Computes the expected number of salt search attempts for a given `DesiredTraits` configuration based on probability.

```APIDOC
## estimateAttempts(desired)

### Description
Computes the expected number of salt search attempts for a given `DesiredTraits` configuration based on probability.

### Parameters
#### Path Parameters
- **desired** (DesiredTraits) - Required - An object specifying the desired pet traits.
  - **species** (string) - Required - The desired species of the pet.
  - **rarity** (string) - Required - The desired rarity of the pet.
  - **eye** (string) - Required - The desired eye trait.
  - **hat** (string) - Required - The desired hat trait.
  - **shiny** (boolean) - Required - Whether the pet should be shiny.
  - **peak** (string | null) - Optional - A specific peak trait.
  - **dump** (string | null) - Optional - A specific dump trait.

### Request Example
```typescript
import { estimateAttempts } from './src/finder/estimator.ts';

estimateAttempts({ species: 'duck', rarity: 'common', eye: '·', hat: 'none', shiny: false, peak: null, dump: null });
// → 180

estimateAttempts({ species: 'dragon', rarity: 'legendary', eye: '✦', hat: 'wizard', shiny: false, peak: null, dump: null });
// → 86400
```

### Response
#### Success Response (200)
- **attempts** (number) - The estimated number of attempts required.
```

--------------------------------

### Generate Pet Traits from RNG Function

Source: https://context7.com/cpaczek/any-buddy/llms.txt

Generates pet traits from a provided pseudo-random number generator function. This is useful for testing or custom seeding scenarios. Note that rarity is weighted, and common pets always have 'none' for a hat.

```typescript
import { rollFrom } from './src/generation/roll.ts';
import { mulberry32 } from './src/generation/rng.ts';

const rng = mulberry32(0xdeadbeef);
const result = rollFrom(rng);
// result.bones.rarity is weighted: common 60%, uncommon 25%, rare 10%, epic 4%, legendary 1%
// Common pets always have hat: 'none'; others draw from 8 hat options
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.