Claude Code ships with a hidden terminal companion that was never publicly announced. This project reverse-engineers that companion from leaked Claude Code source, so anyone can run one in their own terminal.
Disclaimer: This project is reverse-engineered from leaked Claude Code source code and is not affiliated with or endorsed by Anthropic. For educational and research purposes only.
- 18 unique species — duck, cat, dragon, octopus, robot, and more
- Rarity system — Common → Uncommon → Rare → Epic → Legendary, weighted random selection
- Deterministic generation — appearance is derived from a seeded PRNG keyed on your user ID; the same ID always yields the same companion
- ASCII art sprites — per-species animation frames, hat slots, and face rendering
- Persistent soul — name and personality are saved to
~/.config/buddy/config.json; appearance is rebuilt from the user ID hash, making config tampering ineffective - Interactive commands — hatch, pet, inspect stats, mute, reroll
- Responsive rendering — gracefully degrades on narrow terminals (< 100 columns)
- Speech bubbles — idle quips every 5 seconds; color-coded by rarity
| Tool | Version |
|---|---|
| Bun | Latest |
| Terminal with ANSI color support | — |
| Recommended terminal width | ≥ 100 columns |
git clone git@github.com:SXGC/Buddy.git
cd buddy
bun installbun run start
# or
bun run index.tsxStarts the companion in continuous idle mode. Press Ctrl+C to exit.
| Command | Description |
|---|---|
bun run index.tsx hatch |
Hatch a new companion |
bun run index.tsx pet |
Pet your companion (triggers a heart animation) |
bun run index.tsx info |
Display detailed companion stats |
bun run index.tsx reset |
Clear your companion |
bun run index.tsx mute |
Hide the companion |
bun run index.tsx unmute |
Show the companion again |
bun run index.tsx reroll |
Generate a new random appearance |
bun run index.tsx shiny |
Toggle the shiny variant |
Or use the pre-configured scripts in package.json:
bun run hatch
bun run pet
bun run info
bun run mute
bun run unmute
bun run resetBuddy stores its configuration at ~/.config/buddy/config.json.
{
"userID": "your-identifier-or-uuid",
"companion": {
"name": "Quackers",
"personality": "Enthusiastic about everything, especially naps.",
"hatchedAt": 1711864800000
},
"companionShiny": false,
"companionMuted": false
}Note: Only the companion's "soul" (name, personality, hatch timestamp) is persisted. Appearance attributes — species, rarity, stats, eyes, hat — are regenerated deterministically from the
userIDhash on every run. This design prevents manual config edits from inflating rarity or changing species.
buddy/
├── README.md
├── index.tsx # CLI entry point and command router
├── package.json
├── tsconfig.json
├── bun.lock
├── docs/
│ ├── README.zh.md # Chinese documentation
│ └── assets/
│ └── screenshot-idle.png # Idle mode screenshot
└── src/
├── App.tsx # Default idle-mode React component
├── buddy/
│ ├── companion.ts # Companion generation (seeded PRNG)
│ ├── types.ts # Species, rarity, stat type definitions
│ ├── sprites.ts # ASCII art sprite definitions and animation frames
│ ├── CompanionSprite.tsx # Sprite renderer with animations and speech bubbles
│ ├── prompt.ts # Prompt integration helpers
│ └── useBuddyNotification.tsx # Notification hook stubs
├── hooks/
│ └── useTerminalSize.ts # Terminal dimension detection
├── shims/
│ ├── AppState.tsx # React context for global app state
│ ├── config.ts # Read/write ~/.config/buddy/config.json
│ ├── notifications.tsx # Notification system
│ ├── ink.ts # Ink component re-exports
│ ├── stringWidth.ts # String width utility (ANSI-safe)
│ ├── theme.ts # Theme configuration (stub)
│ ├── thinking.ts # Thinking indicator (stub)
│ ├── fullscreen.ts # Fullscreen detection
│ └── bun-bundle.ts # Bun bundling helpers
└── hatch.ts # Companion creation and reroll logic
| Layer | Library |
|---|---|
| Runtime | Bun |
| UI Framework | React 18 |
| Terminal UI | Ink 5 |
| Language | TypeScript 5 (strict mode) |
| Unicode utilities | figures, string-width |
Duck, Cat, Dragon, Octopus, Robot, Crab, Ghost, Bunny, Frog, Bear, Fox, Owl, Penguin, Hamster, Axolotl, Capybara, Platypus, Narwhal.
| Rarity | Probability |
|---|---|
| Common | 60% |
| Uncommon | 25% |
| Rare | 10% |
| Epic | 4% |
| Legendary | 1% |
Higher rarity companions receive more visual accessories (hats, eye styles) and higher base stats.
Every companion has 5 stats scaled by rarity:
- DEBUGGING — aptitude for hunting down bugs
- PATIENCE — tolerance for long compile times
- CHAOS — tendency to suggest questionable refactors
- WISDOM — accumulated programming knowledge
- SNARK — commentary sharpness
- Eyes: 6 styles —
·,✦,×,◉,@,° - Hats: 8 types — crown, tophat, wizard, beret, party, propeller, flower, halo
- Shiny variant: 1% chance; can also be toggled manually
- Personality: Selected at hatch from 20 personality archetypes
- Seeded PRNG (Mulberry32): All companion attributes are derived from a hash of the
userID. The same ID always produces the same companion appearance. - Soul vs. Bones separation: Only mutable "soul" data (name, personality) is written to disk. Immutable "bones" (species, rarity, visual traits) live entirely in the PRNG output.
- Shim layer (
src/shims/): Provides abstraction points for configuration, theming, notifications, and Ink components — making it straightforward to embed Buddy into a larger application. - Responsive layout: The
useTerminalSizehook detects terminal dimensions; the sprite renderer switches to a compact "narrow mode" below 100 columns.
# Run directly with Bun (no build step needed)
bun run index.tsx hatch
# Type-check
bun tsc --noEmitBun handles TypeScript and JSX natively, so there is no separate compile step.
This project is reverse-engineered from leaked Claude Code source code. Copyright ownership is disputed. Use at your own discretion.