How 1270011/claude-buddy works
1. What this repository is
- claude-buddy is a local Claude Code extension package, not a standalone app or remote service.
- Its job is to reintroduce the “buddy” experience through Claude Code’s supported extension points: MCP, skills, hooks, and the status line.
2. Top-level architecture
- The repo is split into four runtime-facing areas:
- server/ for the MCP server and buddy domain logic
- skills/buddy/ for /buddy command routing
- hooks/ for Claude Code event hooks
- statusline/ for terminal rendering
- cli/ provides installation, maintenance, diagnostics, and user-facing commands that wire those pieces into Claude Code.
3. Primary runtime boundary: Claude Code vs local buddy components
- Claude Code is the host application.
- All buddy behavior is implemented locally in Bun/TypeScript plus shell scripts.
- No external backend is used; the main shared dependency is the local filesystem, especially the Claude profile/config directory.
4. MCP server subsystem
- server/index.ts is the server entrypoint, with server/mcp-launcher.sh acting as the launch bridge.
- The server exposes buddy-related tools and instructions through MCP so Claude can query or update buddy state.
- The server domain is decomposed into focused modules: engine, art, reactions, state, suggestions, memory, mood, xp, achievements, theme, path, and related helpers.
5. Buddy identity and generation pipeline
- Buddy generation is deterministic: the README calls out wyhash + mulberry32 and identity derived from the Claude account UUID.
- That identity drives species selection, rarity, stats, and cosmetics so the same profile consistently gets the same buddy.
- This means “generation” is really a repeatable lookup/derivation flow, not a random runtime service.
6. Persistent state model
- Buddy state is stored per Claude profile, with profile-specific paths controlled by CLAUDE_CONFIG_DIR.
- The installer creates isolated state under a profile-specific buddy-state location, so separate Claude profiles do not interfere with each other.
- server/state.ts and cli/backup.ts suggest the state includes saved buddies, settings, and other mutable metadata that can be backed up or restored.
7. Claude Code skill layer
- skills/buddy/SKILL.md is the slash-command interface for /buddy.
- This layer is the command router for user actions like show, pet, stats, rename, save/list/dismiss, frequency, style, position, rarity, width, margin, and statusline toggles.
- It is the main UX boundary between the user and the underlying MCP/state machinery.
8. Hook-based reaction system
- hooks/ contains shell hooks that respond to Claude Code lifecycle events.
- The README identifies two important hook behaviors:
- Post-tool-use hooks that detect errors, test failures, and large diffs
- Stop hooks that extract invisible <!-- buddy: ... --> comments from Claude responses
- These hooks form the “reactive” part of the system, turning Claude output and tool results into buddy comments or mood changes.
9. Status line rendering subsystem
- statusline/buddy-status.sh and statusline/combined-status.sh generate the terminal status line display.
- The status line is responsible for animated ASCII art, rarity color, right alignment, and optional combined usage bars.
- statusline/emoji-widths.data and the testing scripts indicate terminal-width and Unicode alignment are important implementation concerns.
10. Installer and operational CLI
- cli/install.ts, cli/uninstall.ts, cli/upgrade.ts, cli/enable.ts, cli/disable.ts, cli/settings.ts, cli/backup.ts, cli/doctor.ts, cli/verify.ts, cli/show.ts, and cli/pick.ts provide the lifecycle operations.
- This layer edits Claude Code configuration, installs the MCP server and hooks, manages state snapshots, and offers diagnostics.
- cli/tui.tsx and the picker-related commands show that some maintenance workflows are interactive rather than purely scripted.
11. Diagnostics and validation
- The repo includes extensive test coverage under server/*.test.ts and CLI/statusline test scripts.
- bun run doctor, bun run test-statusline, and bun run verify are meant to validate environment, rendering, and deterministic generation.
- This makes the repo architecture easier to trust: there are separate checks for config wiring, runtime behavior, and visual output.
12. Tooling and runtime
- The project is Bun-first: bun.lock, Bun scripts, and a Bun-based TypeScript codebase.
- Shell scripts are used where integration with Claude Code or terminal behavior is simpler than TypeScript.
- CI is GitHub Actions-based (.github/workflows/ci.yml), which likely runs the test and validation matrix for the local extension package.
13. How to draw the system
- A good diagram would place Claude Code at the center, with four inbound/outbound extension paths:
- MCP server for buddy tools and instructions
- Skill for /buddy command handling
- Hooks for event-driven reactions
- Status line for continuous terminal display
- Around those, show the local persistence layer in the Claude profile directory and the CLI installer/maintainer as the component that provisions everything.
Main entry points: engine.ts Buddy engine · buddy-status.sh Buddy line · install.ts Install · state.ts Buddy state
Components 23
Claude Code
External host application that loads the buddy extension points.
- Claude Code · The host app that consumes the extension points.
CLI
Installation, maintenance, diagnostics, and lifecycle commands.
- CLI entry · Top-level command dispatcher for install, upgrade, diagnose, and utilities.
cli/index.ts - Install · Wires the server, hooks, status line, and config into Claude Code.
cli/install.ts - Manage · Upgrade, enable/disable, uninstall, settings, backup, verify, doctor, and show flows.
cli/upgrade.ts - Picker UI · Interactive maintenance and selection workflow.
cli/tui.tsx
MCP server
Buddy logic exposed through Claude Code's MCP boundary.
- MCP launcher · Shell bridge that starts the MCP server for Claude Code.
server/mcp-launcher.sh - Server entry · MCP entrypoint that exposes buddy tools and instructions.
server/index.ts - Buddy engine · Deterministic buddy identity and orchestration logic.
server/engine.ts - Reactions · Interprets errors, diffs, and Claude comments into buddy reactions.
server/reactions.ts - Mood · Tracks and shifts buddy mood from reactive inputs.
server/mood.ts - Art · Generates buddy visuals and ASCII art.
server/art.ts - XP · Experience, awards, and advancement logic.
server/xp.ts - Achievements · Unlocks and records milestone achievements.
server/achievements.ts - Suggestions · Buddy suggestions and guidance surfaced to Claude Code.
server/suggestions.ts - Theme · Color and presentation choices tied to buddy identity.
server/theme.ts
Skill
Slash-command routing for /buddy interactions.
- Buddy skill · Routes /buddy commands like show, pet, stats, rename, save, and statusline controls.
skills/buddy/SKILL.md
Hooks
Event-driven reactions from Claude Code lifecycle events.
- Hook config · Declares Claude Code hook wiring for buddy reactions.
hooks/hooks.json - Hook scripts · Post-tool-use and stop hooks that react to Claude activity.
hooks/react.sh
Status line
Terminal rendering and live buddy display.
- Buddy line · Animated buddy status line with rarity, alignment, and display logic.
statusline/buddy-status.sh - Combined line · Combined status line variant with usage bars and buddy output.
statusline/combined-status.sh
Persistence
Profile-scoped state and filesystem-backed identity.
- Profile dir · Claude profile-scoped config and state location.
- Buddy state · Per-profile mutable state for saved buddies, settings, and metadata.
server/state.ts - Paths · Resolves profile-scoped storage and repo-relative locations.
server/path.ts
Connections 36
- CLI entry → Install: dispatches · CLI entry routes to installation workflows.
- CLI entry → Manage: dispatches · CLI entry routes to maintenance and diagnostics commands.
- CLI entry → Picker UI: launches · CLI entry can open interactive picker workflows.
- Install → MCP launcher: installs · Provisioning wires the MCP launch bridge into Claude Code.
- Install → Hook config: enables · Installer registers hook configuration.
- Install → Buddy line: configures · Installer wires the status line into Claude Code.
- Install → Profile dir: initializes · Installer creates profile-scoped buddy state.
- Manage → Buddy state: backs up · Lifecycle commands inspect, snapshot, and restore persisted buddy state.
- Manage → Profile dir: reads/writes · Maintenance commands edit Claude profile configuration and state.
- Picker UI → Profile dir: selects · Interactive UI helps choose profile-scoped targets.
- MCP launcher → Server entry: starts · Shell bridge launches the MCP server process.
- Server entry → Buddy engine: coordinates · Server entry delegates buddy behavior to domain modules.
- Buddy engine → Buddy state: persists · Core logic reads and updates buddy state.
- Buddy engine → Paths: resolves · Core logic uses profile-aware path resolution.
- Buddy engine → Art: renders · Buddy identity flows into art generation.
- Buddy engine → Theme: themes · Core logic derives presentation from identity and rarity.
- Buddy engine → XP: advances · Core logic updates progression.
- Buddy engine → Achievements: unlocks · Core logic records milestone achievements.
- Buddy engine → Suggestions: advises · Core logic emits buddy suggestions.
- Reactions → Mood: shifts · Hooked events update mood state.
- Reactions → Buddy state: records · Reactions may be stored in profile state.
- Hook scripts → Reactions: invokes · Hook scripts feed Claude events into reaction logic.
- Hook scripts → Mood: updates · Hook reactions can affect mood directly.
- Hook scripts → Buddy state: reads/writes · Hook scripts interact with persisted buddy state.
- Buddy skill → Server entry: queries · Slash commands surface buddy data through the MCP server.
- Buddy skill → Buddy state: updates · User actions change saved buddy state and settings.
- Buddy skill → Buddy line: toggles · Skill commands control status line behavior.
- Buddy line → Art: displays · Status line renders buddy visuals.
- Buddy line → Theme: colors · Status line uses rarity and theme output.
- Combined line → Buddy line: extends · Combined variant builds on the core buddy line.
- Paths → Profile dir: targets · Path logic anchors state beneath the Claude profile directory.
- Claude Code → MCP launcher: loads · Claude Code starts the MCP server via the launch bridge.
- Claude Code → Buddy skill: invokes · Claude Code exposes the /buddy skill interface.
- Claude Code → Hook scripts: triggers · Lifecycle events drive hook execution.
- Claude Code → Buddy line: renders · Claude Code shows the status line in-terminal.
- Claude Code → Profile dir: stores · Claude profile configuration and extension state live in the local filesystem.