# 1270011/claude-buddy architecture

> Architecture diagram of the GitHub repository 1270011/claude-buddy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1270011/claude-buddy
- Repository: https://github.com/1270011/claude-buddy

## Overview

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: [`server/engine.ts`](https://github.com/1270011/claude-buddy/blob/main/server/engine.ts) (Buddy engine), [`statusline/buddy-status.sh`](https://github.com/1270011/claude-buddy/blob/main/statusline/buddy-status.sh) (Buddy line), [`cli/install.ts`](https://github.com/1270011/claude-buddy/blob/main/cli/install.ts) (Install), [`server/state.ts`](https://github.com/1270011/claude-buddy/blob/main/server/state.ts) (Buddy state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Claude Code"]
  node_claude_code["Claude Code<br/>host"]
end

subgraph group_cli["CLI"]
  node_cli_index["CLI entry<br/>command entry<br/>[index.ts]"]
  node_cli_install["Install<br/>provisioning<br/>[install.ts]"]
  node_cli_manage["Manage<br/>lifecycle tools<br/>[upgrade.ts]"]
  node_cli_tui(("Picker UI<br/>interactive cli<br/>[tui.tsx]"))
end

subgraph group_server["MCP server"]
  node_server_launch["MCP launcher<br/>bridge script<br/>[mcp-launcher.sh]"]
  node_server_entry["Server entry<br/>mcp server<br/>[index.ts]"]
  node_server_core["Buddy engine<br/>domain core<br/>[engine.ts]"]
  node_server_react["Reactions<br/>event logic<br/>[reactions.ts]"]
  node_server_mood["Mood<br/>state logic<br/>[mood.ts]"]
  node_server_art["Art<br/>render logic<br/>[art.ts]"]
  node_server_xp["XP<br/>progression<br/>[xp.ts]"]
  node_server_achievements["Achievements<br/>progression<br/>[achievements.ts]"]
  node_server_suggestions["Suggestions<br/>advisor<br/>[suggestions.ts]"]
  node_server_theme["Theme<br/>presentation<br/>[theme.ts]"]
end

subgraph group_skill["Skill"]
  node_skill_buddy["Buddy skill<br/>slash-command skill<br/>[SKILL.md]"]
end

subgraph group_hooks["Hooks"]
  node_hooks_config["Hook config<br/>hook routing<br/>[hooks.json]"]
  node_hooks_runtime["Hook scripts<br/>shell hooks<br/>[react.sh]"]
end

subgraph group_statusline["Status line"]
  node_statusline_main["Buddy line<br/>terminal renderer<br/>[buddy-status.sh]"]
  node_statusline_combo["Combined line<br/>terminal renderer<br/>[combined-status.sh]"]
end

subgraph group_storage["Persistence"]
  node_config_dir[("Profile dir<br/>filesystem")]
  node_server_state[("Buddy state<br/>persistence model<br/>[state.ts]")]
  node_server_path["Paths<br/>filesystem logic<br/>[path.ts]"]
end

node_cli_index -->|"dispatches"| node_cli_install
node_cli_index -->|"dispatches"| node_cli_manage
node_cli_index -->|"launches"| node_cli_tui
node_cli_install -->|"installs"| node_server_launch
node_cli_install -->|"enables"| node_hooks_config
node_cli_install -->|"configures"| node_statusline_main
node_cli_install -->|"initializes"| node_config_dir
node_cli_manage -->|"backs up"| node_server_state
node_cli_manage -->|"reads/writes"| node_config_dir
node_cli_tui -->|"selects"| node_config_dir
node_server_launch -->|"starts"| node_server_entry
node_server_entry -->|"coordinates"| node_server_core
node_server_core -->|"persists"| node_server_state
node_server_core -->|"resolves"| node_server_path
node_server_core -->|"renders"| node_server_art
node_server_core -->|"themes"| node_server_theme
node_server_core -->|"advances"| node_server_xp
node_server_core -->|"unlocks"| node_server_achievements
node_server_core -->|"advises"| node_server_suggestions
node_server_react -->|"shifts"| node_server_mood
node_server_react -->|"records"| node_server_state
node_hooks_runtime -->|"invokes"| node_server_react
node_hooks_runtime -->|"updates"| node_server_mood
node_hooks_runtime -->|"reads/writes"| node_server_state
node_skill_buddy -->|"queries"| node_server_entry
node_skill_buddy -->|"updates"| node_server_state
node_skill_buddy -->|"toggles"| node_statusline_main
node_statusline_main -->|"displays"| node_server_art
node_statusline_main -->|"colors"| node_server_theme
node_statusline_combo -->|"extends"| node_statusline_main
node_server_path -->|"targets"| node_config_dir
node_claude_code -->|"loads"| node_server_launch
node_claude_code -->|"invokes"| node_skill_buddy
node_claude_code -->|"triggers"| node_hooks_runtime
node_claude_code -->|"renders"| node_statusline_main
node_claude_code -->|"stores"| node_config_dir

click node_cli_index "https://github.com/1270011/claude-buddy/blob/main/cli/index.ts"
click node_cli_install "https://github.com/1270011/claude-buddy/blob/main/cli/install.ts"
click node_cli_manage "https://github.com/1270011/claude-buddy/blob/main/cli/upgrade.ts"
click node_cli_tui "https://github.com/1270011/claude-buddy/blob/main/cli/tui.tsx"
click node_server_launch "https://github.com/1270011/claude-buddy/blob/main/server/mcp-launcher.sh"
click node_server_entry "https://github.com/1270011/claude-buddy/blob/main/server/index.ts"
click node_server_core "https://github.com/1270011/claude-buddy/blob/main/server/engine.ts"
click node_server_state "https://github.com/1270011/claude-buddy/blob/main/server/state.ts"
click node_server_react "https://github.com/1270011/claude-buddy/blob/main/server/reactions.ts"
click node_server_mood "https://github.com/1270011/claude-buddy/blob/main/server/mood.ts"
click node_server_art "https://github.com/1270011/claude-buddy/blob/main/server/art.ts"
click node_server_xp "https://github.com/1270011/claude-buddy/blob/main/server/xp.ts"
click node_server_achievements "https://github.com/1270011/claude-buddy/blob/main/server/achievements.ts"
click node_server_suggestions "https://github.com/1270011/claude-buddy/blob/main/server/suggestions.ts"
click node_server_theme "https://github.com/1270011/claude-buddy/blob/main/server/theme.ts"
click node_server_path "https://github.com/1270011/claude-buddy/blob/main/server/path.ts"
click node_skill_buddy "https://github.com/1270011/claude-buddy/blob/main/skills/buddy/SKILL.md"
click node_hooks_config "https://github.com/1270011/claude-buddy/blob/main/hooks/hooks.json"
click node_hooks_runtime "https://github.com/1270011/claude-buddy/blob/main/hooks/react.sh"
click node_statusline_main "https://github.com/1270011/claude-buddy/blob/main/statusline/buddy-status.sh"
click node_statusline_combo "https://github.com/1270011/claude-buddy/blob/main/statusline/combined-status.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_code,node_config_dir,node_server_state,node_server_path toneBlue
class node_cli_index,node_cli_install,node_cli_manage,node_cli_tui toneAmber
class node_server_launch,node_server_entry,node_server_core,node_server_react,node_server_mood,node_server_art,node_server_xp,node_server_achievements,node_server_suggestions,node_server_theme toneMint
class node_skill_buddy toneRose
class node_hooks_config,node_hooks_runtime toneIndigo
class node_statusline_main,node_statusline_combo toneTeal
```

## Components

### Claude Code

External host application that loads the buddy extension points.

- **Claude Code**: host · The host app that consumes the extension points.

### CLI

Installation, maintenance, diagnostics, and lifecycle commands.

- [CLI entry](https://github.com/1270011/claude-buddy/blob/main/cli/index.ts): command entry · Top-level command dispatcher for install, upgrade, diagnose, and utilities. · `cli/index.ts`
- [Install](https://github.com/1270011/claude-buddy/blob/main/cli/install.ts): provisioning · Wires the server, hooks, status line, and config into Claude Code. · `cli/install.ts`
- [Manage](https://github.com/1270011/claude-buddy/blob/main/cli/upgrade.ts): lifecycle tools · Upgrade, enable/disable, uninstall, settings, backup, verify, doctor, and show flows. · `cli/upgrade.ts`
- [Picker UI](https://github.com/1270011/claude-buddy/blob/main/cli/tui.tsx): interactive cli · Interactive maintenance and selection workflow. · `cli/tui.tsx`

### MCP server

Buddy logic exposed through Claude Code's MCP boundary.

- [MCP launcher](https://github.com/1270011/claude-buddy/blob/main/server/mcp-launcher.sh): bridge script · Shell bridge that starts the MCP server for Claude Code. · `server/mcp-launcher.sh`
- [Server entry](https://github.com/1270011/claude-buddy/blob/main/server/index.ts): mcp server · MCP entrypoint that exposes buddy tools and instructions. · `server/index.ts`
- [Buddy engine](https://github.com/1270011/claude-buddy/blob/main/server/engine.ts): domain core · Deterministic buddy identity and orchestration logic. · `server/engine.ts`
- [Reactions](https://github.com/1270011/claude-buddy/blob/main/server/reactions.ts): event logic · Interprets errors, diffs, and Claude comments into buddy reactions. · `server/reactions.ts`
- [Mood](https://github.com/1270011/claude-buddy/blob/main/server/mood.ts): state logic · Tracks and shifts buddy mood from reactive inputs. · `server/mood.ts`
- [Art](https://github.com/1270011/claude-buddy/blob/main/server/art.ts): render logic · Generates buddy visuals and ASCII art. · `server/art.ts`
- [XP](https://github.com/1270011/claude-buddy/blob/main/server/xp.ts): progression · Experience, awards, and advancement logic. · `server/xp.ts`
- [Achievements](https://github.com/1270011/claude-buddy/blob/main/server/achievements.ts): progression · Unlocks and records milestone achievements. · `server/achievements.ts`
- [Suggestions](https://github.com/1270011/claude-buddy/blob/main/server/suggestions.ts): advisor · Buddy suggestions and guidance surfaced to Claude Code. · `server/suggestions.ts`
- [Theme](https://github.com/1270011/claude-buddy/blob/main/server/theme.ts): presentation · Color and presentation choices tied to buddy identity. · `server/theme.ts`

### Skill

Slash-command routing for /buddy interactions.

- [Buddy skill](https://github.com/1270011/claude-buddy/blob/main/skills/buddy/SKILL.md): slash-command 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](https://github.com/1270011/claude-buddy/blob/main/hooks/hooks.json): hook routing · Declares Claude Code hook wiring for buddy reactions. · `hooks/hooks.json`
- [Hook scripts](https://github.com/1270011/claude-buddy/blob/main/hooks/react.sh): shell hooks · Post-tool-use and stop hooks that react to Claude activity. · `hooks/react.sh`

### Status line

Terminal rendering and live buddy display.

- [Buddy line](https://github.com/1270011/claude-buddy/blob/main/statusline/buddy-status.sh): terminal renderer · Animated buddy status line with rarity, alignment, and display logic. · `statusline/buddy-status.sh`
- [Combined line](https://github.com/1270011/claude-buddy/blob/main/statusline/combined-status.sh): terminal renderer · Combined status line variant with usage bars and buddy output. · `statusline/combined-status.sh`

### Persistence

Profile-scoped state and filesystem-backed identity.

- **Profile dir**: filesystem · Claude profile-scoped config and state location.
- [Buddy state](https://github.com/1270011/claude-buddy/blob/main/server/state.ts): persistence model · Per-profile mutable state for saved buddies, settings, and metadata. · `server/state.ts`
- [Paths](https://github.com/1270011/claude-buddy/blob/main/server/path.ts): filesystem logic · Resolves profile-scoped storage and repo-relative locations. · `server/path.ts`

## Connections

- 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.