A Tamagotchi-style virtual pet that lives in your menubar and tracks your Claude Code sessions. Watch your crabs wander around while Claude works!
- Multi-Session Tracking: Automatically detects all active Claude Code sessions via hooks
- Unique Accessories: Each repo gets a unique accessory (bow, star, heart, etc.) so you can tell them apart
- Wandering Crabs: Your pets walk around sideways like real crabs
- Repo Health Stats: Tracks energy, health, happiness, and discipline based on:
- Commit frequency (energy)
- Uncommitted changes (health)
- CLAUDE.md presence (happiness + discipline)
- Test directory presence (happiness + discipline)
- Interactive: Click to see stats, double-click to pet them
- Thought Bubbles: Crabs share random thoughts while working
Download the latest .dmg from the Releases page.
# Clone the repo
git clone https://github.com/stevysmith/clawdgotchi.git
cd clawdgotchi
# Install dependencies
npm install
# Run in development mode
npm run electron:dev
# Build for production
npm run electron:buildClawdGotchi uses Claude Code's hooks system to track active sessions:
- On first launch, it installs a hook to
~/.claude/hooks/ - When you start a Claude Code session, the hook notifies ClawdGotchi
- A new crab appears in your menubar with a unique accessory based on the repo
- Stats update based on your repo's git health
- When the session ends, the crab falls asleep and fades away
| Stat | What Affects It |
|---|---|
| Energy | How recently you committed (< 1 hour = 100%) |
| Health | Number of uncommitted changes (0 = 100%) |
| Happiness | CLAUDE.md + tests + recent commits + clean state |
| Discipline | CLAUDE.md + tests + few uncommitted files |
- Commit early and often to keep energy high
- Keep uncommitted changes under 5 files for good health
- Add a
CLAUDE.mdfile to boost happiness and discipline - Create a
tests/or__tests__/directory for extra happiness
- Node.js 18+
- npm or yarn
- macOS (for Electron menubar)
clawdgotchi/
├── electron/ # Electron main process
│ ├── main.ts # App entry, tray, window
│ ├── preload.ts # IPC bridge
│ ├── socketServer.ts # Unix socket for hook events
│ ├── sessionManager.ts # Session state management
│ └── hookInstaller.ts # Installs hooks to ~/.claude/
├── src/ # React renderer
│ ├── App.tsx # Main app component
│ └── components/
│ ├── ClawdGotchi.tsx # The crab SVG
│ ├── WanderingCrab.tsx # Animated wandering crab
│ ├── MultiPetView.tsx # Multi-session arena
│ └── accessories/ # Accessory SVG components
├── assets/
│ └── hooks/ # Python hook script
└── package.json
npm run dev # Vite dev server only
npm run electron:dev # Full Electron dev mode
npm run build # Build for production
npm run electron:build # Build + package as DMG- Make sure ClawdGotchi is running (check menubar)
- Restart ClawdGotchi to reinstall hooks
- Check hooks are installed:
cat ~/.claude/settings.json | grep clawdgotchi
Sessions go idle after 5 minutes of no activity. They'll wake up when Claude starts working again.
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
MIT - see LICENSE
Made with love by the Claude Code community