ClaudePet
Free & open source · macOS menu bar

Claude Code,
with a pulse.

A small companion that lives in your menu bar, reacts to every session in real time, keeps score of your streaks, and taps you on the shoulder only when it actually matters.

Download for macOS View on GitHub

Now at v1.1.5 — usage quotas, mood & streaks, budget alerts, and a lot more since v1.1.0.

ClaudePet showing a live tool call and task progress ring ClaudePet showing a done, ready-for-review state ClaudePet waiting for a permission decision ClaudePet reacting to a failed build
WORKING

Real, unedited — captured live from an actual session.

Idle
Working
Needs permission
Ready for review
Failed
State machine

Five moods. One glance.

Real, unedited captures — the pet reacting live to an actual Claude Code session, not mockups.

ClaudePet showing a live tool call and task progress ring

Working

PreToolUse / PostToolUse

ClaudePet showing a done, ready-for-review state

Ready for review

Stop hook · decays in 20s

ClaudePet waiting for a permission decision

Needs you

PermissionRequest

ClaudePet reacting to a failed build

Failed

PostToolUseFailure

Priority when several sessions are active: needs‑you > failed > ready‑for‑review > working > idle — the same order the Activity Tray sorts by.

Notifications

It knows when to bother you.
And, just as importantly, when not to.

🙋
Claude Code needs your permission
claudepet
Wants to use Bash
✅
Fix flaky notification tests finished
claudepet
4/4 tasks · 12m
💰
Today's spend crossed your budget
Est. $10.42 so far, budget is $10.00.

Permission requests and finished sessions notify you unconditionally — even while you're looking right at the pet — because those are the two moments you can't afford to miss. Everything else stays out of your way until you actually need it.

Personality

It remembers every session you've ever run.

Streaks, levels, and a per-project skin — all derived locally from your own history log, never uploaded anywhere.

  • Daily streaks that track consecutive days you've actually used Claude Code — a gap day breaks it, same as any habit tracker.
  • XP & levels earned from finished sessions and completed tasks, shown as a subtle warm tint on the pet itself at higher levels.
  • Per-project skins — assign a different pet to each repo from the gallery, so you know which project is talking to you at a glance.
Session Stats
🔥 5d ⭐ Lv 3
🦊claudepet 🐢atlas-core 🦉drones-ui
Insights

Know exactly where you stand.

Spend, quota, and history — read straight from Claude Code's own data, entirely on your Mac.

Session Stats, properly graphed

A 14-day spend trend, a per-project cost breakdown, and daily/weekly session & task counters — computed the moment a session ends, not estimated after the fact.

  • Daily budget alerts, once per day, the moment your estimated spend crosses a threshold you set.
  • A weekly digest notification: sessions, tasks, hours worked, and est. cost, delivered once a week.
$4.82
Spend, last 7 days
65% left
5h quota
38% left
7d quota

Your Claude usage, one click away

Opt in once, and your 5-hour and 7-day rate-limit quota shows up right in the menu bar dropdown — color-coded green, orange, or red — without ever touching your own terminal statusline.

  • Chains through to whatever statusLine script you already have — your terminal's own output is completely unaffected.
  • Entirely opt-in from Hook Setup & Diagnostics — off by default, on with one click.
⚡ 65% 5h left📅 38% 7d left
Tuck Away Pet (⌘⇧P)
Jump to Session… (⌘⇧K)
Pet Gallery…
Session Stats…
Preferences…
Workflow

One click closer to the terminal.

Right-click the bubble for the exact session you're looking at — no more hunting through windows.

Bring to Front
Copy Summary
Reveal Transcript in Finder
End Session
  • Quick actions on the bubble and every tray row — bring the right terminal tab forward, copy the summary, open the raw transcript, or end the session.
  • Command palette (⌘⇧K) — a Spotlight-style fuzzy jump to any active session by project name.
  • Multi-monitor docking — pin the pet to a specific display and corner; it re-clamps automatically when you plug or unplug a screen.
How it works

No first-party API — so it watches a folder instead

Claude Code is a CLI. There's no window to hook into, so ClaudePet bridges it with hooks (writing state) and a menu-bar app (watching state).

1

A hook fires

Claude Code already runs hooks on every prompt, tool call, and permission check — one JSON snippet merged into your settings wires them up.

2

A tiny script writes state

A stdlib-only Python bridge writes one small JSON file per session — fast enough to never add latency to your turn.

3

The pet reacts, instantly

A Unix socket ping wakes the app the moment the file changes, so the pet's pose and status line update in milliseconds, not on a poll.

~/.claude/pet/sessions/<id>.json
# PermissionRequest hook fires -> session_id: "a1b2c3d4" state: "waiting-permission" action: "Needs permission: running `rm -rf tmp/`" tty: "/dev/ttys002" # -> notify-requests.sock ping # -> native notification fires # -> pet shows its waiting pose
Thoughtful by design

Set up once. Forget it exists.

The small things that make a menu-bar app worth leaving running for months.

👋

Guided first run

A short welcome tour explains every pet state and hotkey before handing off to a one-click hook installer — no README required.

♿︎

Accessible

VoiceOver labels on the pet bubble, tray rows, and stats tiles — the state machine is announced, not just shown.

🌍

Built for more languages

Localization groundwork is already in place, starting with the menu bar — the rest of the UI migrates the same way over time.

🔁

Launches with your Mac

Turn on Launch at Login from Preferences and it's just always there — no need to remember to open it.

🔧

Self-diagnosing

Hook Setup & Diagnostics doubles as the fix for "the pet just isn't reacting" — a health check, not a support ticket.

🔒

Local, always

Every number ClaudePet shows you — cost, streaks, quota — is computed on your Mac from files already on your Mac. Nothing is ever uploaded.

Install

Two minutes, no App Store

A plain .app bundle plus one hook snippet merged into your Claude Code settings.

zsh — install
# 1. Download and unzip open ~/Downloads/ClaudePet.zip # drag ClaudePet.app to Applications, launch it # 2. Wire up the hooks # Menu bar -> "Hook Setup & Diagnostics..." -> Install # (backs up settings.json for you, automatically)

Ad-hoc signed, not notarized — right-click → Open on first launch, or run xattr -dr com.apple.quarantine on the app.

zsh — build from source
# Requires macOS 13+, Swift 5.9+ git clone https://github.com/MOHAMEDSAMEER78/claudepet cd claudepet ./build_app.sh release open ClaudePet.app

Xcode Command Line Tools is enough — no Xcode project needed. Full hook wiring and custom-pet instructions are in the README.

Ready when you are

Give your terminal a companion.

Free, open source, and it never phones home.

Download for macOS View on GitHub