https://github.com/qaz61328/claudepet
macOS desktop pet that brings Claude Code notifications to life with pixel-art characters.
https://github.com/qaz61328/claudepet
appkit claude-code desktop-pet macos menubar pixel-art swift
Last synced: 3 months ago
JSON representation
macOS desktop pet that brings Claude Code notifications to life with pixel-art characters.
- Host: GitHub
- URL: https://github.com/qaz61328/claudepet
- Owner: qaz61328
- License: mit
- Created: 2026-03-26T17:46:57.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T07:38:53.000Z (3 months ago)
- Last Synced: 2026-04-03T09:38:56.645Z (3 months ago)
- Topics: appkit, claude-code, desktop-pet, macos, menubar, pixel-art, swift
- Language: Swift
- Homepage:
- Size: 3.27 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# ClaudePet
Your desktop buddy for Claude Code. Intercepts permissions, pops notifications, mumbles to itself.
A pixel-art desktop pet that lives next to your terminal.
It replaces Claude Code's permission prompts with clickable speech bubbles,
notifies you when work is done, and occasionally talks to itself when bored.
Create your own character with custom dialogue, sprites, and sounds.
## Features
- Pixel-art character with idle, bow, alert, and happy animations
- Speech bubbles for work complete, needs input, and plan ready events
- Allow once, always allow, or deny — replaces terminal permission prompts
- Idle chatter when bored — ClaudePet runs an external script to generate persona-flavored lines
- Persona system with custom dialogue, sprites, and sound effects
- Status bar menu for visibility, persona switching, and chatter control
- Auto-launch with every `claude` invocation
## How it works
ClaudePet runs an HTTP server on `127.0.0.1:23987`. Two Claude Code hooks feed it events: a Stop hook sends notifications when work finishes, and a PreToolUse hook intercepts tool calls that need authorization. The authorization bubble holds the HTTP connection until you click allow or deny, so Claude Code pauses in the meantime.
"Always Allow" remembers the tool name for the rest of the session. The memory clears when ClaudePet exits.
For the full HTTP API, animation state machine, and hook integration details, see [CLAUDE.md](CLAUDE.md).
## Quick start
Requirements: macOS 13+, Swift 5.9+ (Xcode Command Line Tools), `jq`
```bash
git clone https://github.com/qaz61328/ClaudePet.git
cd ClaudePet
bash scripts/setup.sh
```
The setup script builds the binary, configures Claude Code hooks, checks for LLM providers (idle chatter), and adds a shell wrapper so ClaudePet launches with every `claude` invocation.
For step-by-step instructions or manual configuration, see [SETUP.md](docs/SETUP.md) | [繁體中文](docs/SETUP_zh-TW.md).
## Update
Click **Check for Updates** in the status bar menu. ClaudePet checks the latest GitHub Release and walks you through the upgrade automatically.
To update manually:
```bash
git pull origin main
bash scripts/upgrade.sh
```
The upgrade script rebuilds the binary, updates Claude Code hooks and configs, and restarts ClaudePet.
## Uninstall
```bash
bash scripts/uninstall.sh
```
This removes all ClaudePet environment configs: Claude Code hooks, the shell wrapper, and temp files. It does not delete the repo itself.
## Personas
Every character is fully customizable — dialogue, pixel sprites, and sound effects. Build your own or use the built-in default.
The fastest way: run `/create-persona` inside Claude Code. It walks you through character design and generates everything.
You can also build a persona by hand. Drop a `persona.json` plus optional sprites and sounds into `Personas//`. See [CLAUDE.md](CLAUDE.md) for the full persona architecture.
Switch between installed personas from the status bar menu.
## FAQ
See [FAQ.md](docs/FAQ.md) | [繁體中文](docs/FAQ_zh-TW.md)
## Contributing
This project is built by me and Claude Code together. If you run into any issues, feel free to modify the code yourself or submit a PR. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
## License
[MIT](LICENSE)