petdex-cc 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +311 -311
  3. package/README_CN.md +323 -323
  4. package/dist/bin/cli.js +13 -13
  5. package/dist/src/hooks/write-scripts.js +21 -21
  6. package/dist/src/renderer/index.html +264 -264
  7. package/package.json +48 -48
  8. package/src/hooks/bridge.ps1 +11 -11
  9. package/src/hooks/bridge.sh +9 -9
  10. package/dist/src/renderer/wander.d.ts +0 -8
  11. package/dist/src/renderer/wander.d.ts.map +0 -1
  12. package/dist/src/renderer/wander.js +0 -137
  13. package/dist/src/renderer/wander.js.map +0 -1
package/README.md CHANGED
@@ -1,311 +1,311 @@
1
- <div align="center">
2
-
3
- # petdex-cc
4
-
5
- **Desktop Pet Companion for Claude Code**
6
-
7
- *Animated pets that live on your screen and react to your coding in real-time*
8
-
9
- [![npm version](https://img.shields.io/badge/version-0.1.1-8b5cf6?style=flat-square)](https://www.npmjs.com/package/petdex-cc)
10
- [![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0ea5e9?style=flat-square)]()
11
- [![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?style=flat-square)]()
12
- [![license](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)]()
13
- [![pets](https://img.shields.io/badge/pets-1%2C569%20available-ec4899?style=flat-square)](https://petdex.crafter.run)
14
-
15
- [English](./README.md) · [中文文档](./README_CN.md)
16
-
17
- </div>
18
-
19
- ---
20
-
21
- ## What is petdex-cc?
22
-
23
- petdex-cc brings **animated desktop pets** to your Claude Code workflow. Pick any pet from [Petdex](https://petdex.crafter.run/) (1,569+ community pets), install with one command, and your companion appears on your desktop — reading code with you, celebrating completions, cheering you through errors, and growing stronger as you code.
24
-
25
- > **How is this different from `npx petdex install`?**
26
- > The original `petdex` command gives you a basic pet. `petdex-cc` adds a deep **Claude Code integration layer** — hooks into your coding workflow, a level progression system, AI-generated speech, time-aware greetings, and interactive effects. Your pet isn't just decoration — it *lives* in your coding session.
27
-
28
- ### Features at a glance
29
-
30
- - **Real-time reactions** — pet changes animation when you read, edit, run commands, complete tasks, or hit errors
31
- - **8-level progression** — Byte → Process → Thread → Module → Kernel → Neural → Quantum → Singularity, with escalating visual effects
32
- - **AI speech bubbles** — context-aware dialogue generated by Claude (or built-in preset lines)
33
- - **Time-aware greetings** — morning, lunch, afternoon, evening, night, and midnight messages in Chinese
34
- - **Interactive** — drag your pet anywhere, right-click for menu, rapid-click easter egg
35
- - **System tray** — show/hide, about, quit from the taskbar
36
- - **State persistence** — level and event count survive restarts (HMAC-signed, tamper-resistant)
37
- - **1,569+ pets** — browse [petdex.crafter.run](https://petdex.crafter.run/) and install any community pet
38
-
39
- ---
40
-
41
- ## Quick Start
42
-
43
- ### Prerequisites
44
-
45
- - [Node.js](https://nodejs.org/) >= 18
46
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
47
-
48
- ### Install
49
-
50
- ```bash
51
- # 1. Browse pets → https://petdex.crafter.run/
52
- # 2. Find one you like, note the slug (e.g. "boba")
53
- # 3. Install:
54
-
55
- npx petdex-cc install boba
56
- ```
57
-
58
- Your pet appears on the desktop immediately and starts reacting to Claude Code.
59
-
60
- ### Popular pets
61
-
62
- | Slug | Name | Description |
63
- |---|---|---|
64
- | `boba` | Boba | Tiny otter sipping bubble tea |
65
- | `doraemon` | Doraemon | Blue robot-cat from the future |
66
- | `noir-webling` | Noir Webling | Monochrome spider detective |
67
- | `ikun-hoops` | IKUN Hoops | Hoodie chick with a basketball |
68
- | `ddo-zvzo` | ddo-zvzo | Purple mascot with sunglasses |
69
- | `mochi` | Mochi | Orange-and-white chibi cat |
70
-
71
- > Browse all 1,569+ pets at [**petdex.crafter.run**](https://petdex.crafter.run/)
72
-
73
- ---
74
-
75
- ## What Your Pet Does
76
-
77
- Every Claude Code action triggers a pet reaction:
78
-
79
- | Claude Code event | Pet animation | Speech bubble |
80
- |---|---|---|
81
- | Session starts | Waving | "Let's get to work!" |
82
- | Reading a file | Review | "Reading filename..." |
83
- | Editing a file | Idle | "Edited filename" |
84
- | Running a command | Running | "Running command..." |
85
- | Searching (Glob/Grep) | Waiting | "Searching..." |
86
- | Tool fails | Failed | "Oops, something went wrong" + AI encouragement |
87
- | Task completes | Jumping | "Task complete!" + AI celebration |
88
- | Claude stops | Jumping | "Task complete!" (60% AI speech) |
89
- | Claude errors | Failed | Error message + AI comfort |
90
- | Idle (10+ min) | Waving | Time-aware Chinese greeting |
91
- | Level up | Current state | "Level up! Kernel!" + all effects activate |
92
-
93
- ### Pet interactions
94
-
95
- - **Drag** — click and drag to move your pet anywhere
96
- - **Right-click** — context menu with Show/Hide, About, Quit
97
- - **System tray** — right-click the tray icon for menu
98
- - **Easter egg** — rapidly click your pet for escalating reactions (2 → 4 → 6 → 9 → 12 → 15 clicks)
99
-
100
- ---
101
-
102
- ## Level System
103
-
104
- Your pet levels up based on cumulative Claude Code events. Each level unlocks new visual effects:
105
-
106
- | Lv | Name | Events | Color | Effect |
107
- |:---:|---|---:|---|---|
108
- | 1 | **Byte** | 0 | Silver | Base pet |
109
- | 2 | **Process** | 50 | Green | Breathing glow |
110
- | 3 | **Thread** | 200 | Blue | Rotating aura ring |
111
- | 4 | **Module** | 500 | Purple | Enhanced aura |
112
- | 5 | **Kernel** | 1,000 | Amber | Floating light particles |
113
- | 6 | **Neural** | 2,000 | Pink | Particle storm |
114
- | 7 | **Quantum** | 5,000 | Cyan | Energy field |
115
- | 8 | **Singularity** | 10,000 | Gold | Golden halo + all effects |
116
-
117
- ---
118
-
119
- ## AI Speech
120
-
121
- When an Anthropic API key is available (auto-detected from Claude Code settings or set via `petdex-cc config`), your pet generates **context-aware speech**:
122
-
123
- | Scene | Trigger | Example AI response |
124
- |---|---|---|
125
- | `task_complete` | Task finishes | "做得好！继续加油！" |
126
- | `error` | Tool fails | "别担心，bugs难免的~" |
127
- | `idle` | Idle 10+ minutes | "还在吗？" |
128
- | `level_up` | Level threshold crossed | "升级啦！太厉害了！" |
129
-
130
- - **2-minute cooldown** between AI calls (level-ups bypass this)
131
- - **5-second timeout** — falls back to preset lines if API is slow
132
- - **No API key?** Built-in preset lines work great — 7 task lines, 5 error lines, 5 idle lines, 4 level-up lines
133
-
134
- ---
135
-
136
- ## CLI Reference
137
-
138
- ```bash
139
- petdex-cc install <slug> # Download pet, configure hooks, and launch
140
- petdex-cc start # Start the desktop pet
141
- petdex-cc stop # Gracefully stop the pet
142
- petdex-cc list # Browse all pets from Petdex registry
143
- petdex-cc switch <slug> # Switch pets at runtime (downloads if needed)
144
- petdex-cc status # Show pet name, level, events, running status
145
- petdex-cc uninstall # Remove hooks, stop pet, delete all data
146
- petdex-cc config [options] # Configure settings
147
- ```
148
-
149
- ### Config options
150
-
151
- ```bash
152
- petdex-cc config --api-key <key> # Anthropic API key for AI speech
153
- petdex-cc config --api-base-url <url> # API base URL
154
- petdex-cc config --cooldown <minutes> # AI call cooldown (default: 2)
155
- ```
156
-
157
- > API credentials are auto-detected from `~/.claude/settings.json` — most users don't need manual config.
158
-
159
- ---
160
-
161
- ## Architecture
162
-
163
- ```
164
- ┌─────────────────────────────────────────────────┐
165
- │ Claude Code │
166
- │ (tool use, task complete, errors, idle, etc.) │
167
- └──────────────────────┬──────────────────────────┘
168
- │ hooks (settings.json)
169
- ▼
170
- ┌──────────────────┐
171
- │ bridge.ps1/.sh │ async, 10s timeout
172
- └────────┬─────────┘
173
- │ HTTP POST /event
174
- ▼
175
- ┌─────────────────────────────────────────────────┐
176
- │ petdex-cc (Electron) │
177
- │ │
178
- │ ┌──────────────┐ ┌──────────┐ ┌────────────┐ │
179
- │ │ event-mapper │ │ storage │ │ ai-speech │ │
180
- │ │ event → action│ │ level, XP │ │ Claude Haiku│ │
181
- │ └──────┬───────┘ └─────┬────┘ └─────┬──────┘ │
182
- │ │ │ │ │
183
- │ └─────────┬───────┘ │ │
184
- │ ▼ │ │
185
- │ ┌─────────────────┐ │ │
186
- │ │ IPC to window │◀─────────────┘ │
187
- │ └────────┬────────┘ │
188
- └──────────────────┼──────────────────────────────────┘
189
- ▼
190
- ┌──────────────────┐
191
- │ Pet Window (HTML) │ transparent, always-on-top
192
- │ │
193
- │ ┌─── sprite ───┐ │ 9 animation states
194
- │ │ bubble │ │ 3s / 8s auto-dismiss
195
- │ │ badge │ │ Lv tag + color
196
- │ │ effects │ │ glow/aura/particles/halo
197
- │ └──────────────┘ │
198
- └──────────────────┘
199
- ```
200
-
201
- ---
202
-
203
- ## Developer Setup
204
-
205
- ```bash
206
- git clone https://github.com/devnomad-byte/petdex-cc.git
207
- cd petdex-cc
208
- npm install
209
- npm run build
210
-
211
- # Run in dev mode
212
- npx electron .
213
-
214
- # Install globally for CLI
215
- npm link
216
- petdex-cc install boba
217
- ```
218
-
219
- ### Project structure
220
-
221
- ```
222
- petdex-cc/
223
- ├── bin/cli.ts CLI entry point (8 commands)
224
- ├── src/
225
- │ ├── main/ Electron main process
226
- │ │ ├── index.ts Window creation, event loop, IPC
227
- │ │ ├── server.ts HTTP server (hooks → pet, port 17321)
228
- │ │ ├── ai-speech.ts AI speech via Anthropic Messages API
229
- │ │ ├── storage.ts HMAC-signed state persistence
230
- │ │ ├── tray.ts System tray with cat-face icon
231
- │ │ └── event-mapper.ts 8 hook events → pet actions
232
- │ ├── renderer/ Electron renderer (pet UI)
233
- │ │ ├── index.html Transparent window + CSS effects
234
- │ │ ├── renderer.ts IPC coordination + level effects
235
- │ │ ├── pet-sprite.ts 9-state spritesheet engine
236
- │ │ ├── bubble.ts Speech bubble system
237
- │ │ ├── click-through.ts Transparent click pass-through
238
- │ │ ├── drag.ts Drag + click easter egg
239
- │ │ └── context-menu.ts Right-click menu
240
- │ ├── cli/ CLI command implementations
241
- │ ├── hooks/ Claude Code hooks (register/unregister)
242
- │ │ ├── register.ts Writes to ~/.claude/settings.json
243
- │ │ ├── write-scripts.ts Cross-platform bridge scripts
244
- │ │ ├── bridge.ps1 Windows PowerShell bridge
245
- │ │ └── bridge.sh Unix bash bridge
246
- │ ├── petdex-api/ Petdex registry client
247
- │ │ ├── client.ts Manifest fetch + slug lookup
248
- │ │ └── download.ts Streaming download with progress
249
- │ └── shared/ Shared types and constants
250
- ```
251
-
252
- ---
253
-
254
- ## Configuration Reference
255
-
256
- ### Auto-detected settings
257
-
258
- petdex-cc reads these from `~/.claude/settings.json` automatically:
259
-
260
- | Setting | Used for |
261
- |---|---|
262
- | `ANTHROPIC_AUTH_TOKEN` | API key for AI speech |
263
- | `ANTHROPIC_BASE_URL` | API endpoint for AI speech |
264
-
265
- ### Manual config
266
-
267
- Stored in `~/.petdex-cc/config.json`:
268
-
269
- ```bash
270
- petdex-cc config --api-key <key> --api-base-url <url> --cooldown 2
271
- ```
272
-
273
- ### Data locations
274
-
275
- | Path | Contents |
276
- |---|---|
277
- | `~/.petdex-cc/pets/<slug>/` | Downloaded spritesheet + pet.json |
278
- | `~/.petdex-cc/data/state.json` | Level, events, pet slug (HMAC-signed) |
279
- | `~/.petdex-cc/data/state.sig` | HMAC-SHA256 signature |
280
- | `~/.petdex-cc/hooks/` | Bridge scripts |
281
- | `~/.petdex-cc/config.json` | User config (API key, cooldown) |
282
-
283
- ---
284
-
285
- ## Hooks Reference
286
-
287
- petdex-cc registers these hooks in `~/.claude/settings.json`:
288
-
289
- | Hook | Matcher | What triggers it |
290
- |---|---|---|
291
- | `PostToolUse` | `Read\|Edit\|Write\|Bash\|Glob\|Grep` | After any tool call |
292
- | `PostToolUseFailure` | — | After a tool call fails |
293
- | `Stop` | — | Claude finishes a response |
294
- | `StopFailure` | — | Claude stops with error |
295
- | `Notification` | `idle_prompt` | User is idle |
296
- | `SessionStart` | `startup\|resume` | Claude Code launches or resumes |
297
- | `SessionEnd` | — | Claude Code session ends |
298
- | `TaskCompleted` | — | A task is marked complete |
299
-
300
- ---
301
-
302
- ## License
303
-
304
- [MIT](./LICENSE)
305
-
306
- ---
307
-
308
- <div align="center">
309
- <sub>Built for the <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a> community</sub><br />
310
- <sub>Pets powered by <a href="https://petdex.crafter.run/">Petdex</a></sub>
311
- </div>
1
+ <div align="center">
2
+
3
+ # petdex-cc
4
+
5
+ **Desktop Pet Companion for Claude Code**
6
+
7
+ *Animated pets that live on your screen and react to your coding in real-time*
8
+
9
+ [![npm version](https://img.shields.io/badge/version-0.1.1-8b5cf6?style=flat-square)](https://www.npmjs.com/package/petdex-cc)
10
+ [![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0ea5e9?style=flat-square)]()
11
+ [![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?style=flat-square)]()
12
+ [![license](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)]()
13
+ [![pets](https://img.shields.io/badge/pets-1%2C569%20available-ec4899?style=flat-square)](https://petdex.crafter.run)
14
+
15
+ [English](./README.md) · [中文文档](./README_CN.md)
16
+
17
+ </div>
18
+
19
+ ---
20
+
21
+ ## What is petdex-cc?
22
+
23
+ petdex-cc brings **animated desktop pets** to your Claude Code workflow. Pick any pet from [Petdex](https://petdex.crafter.run/) (1,569+ community pets), install with one command, and your companion appears on your desktop — reading code with you, celebrating completions, cheering you through errors, and growing stronger as you code.
24
+
25
+ > **How is this different from `npx petdex install`?**
26
+ > The original `petdex` command gives you a basic pet. `petdex-cc` adds a deep **Claude Code integration layer** — hooks into your coding workflow, a level progression system, AI-generated speech, time-aware greetings, and interactive effects. Your pet isn't just decoration — it *lives* in your coding session.
27
+
28
+ ### Features at a glance
29
+
30
+ - **Real-time reactions** — pet changes animation when you read, edit, run commands, complete tasks, or hit errors
31
+ - **8-level progression** — Byte → Process → Thread → Module → Kernel → Neural → Quantum → Singularity, with escalating visual effects
32
+ - **AI speech bubbles** — context-aware dialogue generated by Claude (or built-in preset lines)
33
+ - **Time-aware greetings** — morning, lunch, afternoon, evening, night, and midnight messages in Chinese
34
+ - **Interactive** — drag your pet anywhere, right-click for menu, rapid-click easter egg
35
+ - **System tray** — show/hide, about, quit from the taskbar
36
+ - **State persistence** — level and event count survive restarts (HMAC-signed, tamper-resistant)
37
+ - **1,569+ pets** — browse [petdex.crafter.run](https://petdex.crafter.run/) and install any community pet
38
+
39
+ ---
40
+
41
+ ## Quick Start
42
+
43
+ ### Prerequisites
44
+
45
+ - [Node.js](https://nodejs.org/) >= 18
46
+ - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
47
+
48
+ ### Install
49
+
50
+ ```bash
51
+ # 1. Browse pets → https://petdex.crafter.run/
52
+ # 2. Find one you like, note the slug (e.g. "boba")
53
+ # 3. Install:
54
+
55
+ npx petdex-cc install boba
56
+ ```
57
+
58
+ Your pet appears on the desktop immediately and starts reacting to Claude Code.
59
+
60
+ ### Popular pets
61
+
62
+ | Slug | Name | Description |
63
+ |---|---|---|
64
+ | `boba` | Boba | Tiny otter sipping bubble tea |
65
+ | `doraemon` | Doraemon | Blue robot-cat from the future |
66
+ | `noir-webling` | Noir Webling | Monochrome spider detective |
67
+ | `ikun-hoops` | IKUN Hoops | Hoodie chick with a basketball |
68
+ | `ddo-zvzo` | ddo-zvzo | Purple mascot with sunglasses |
69
+ | `mochi` | Mochi | Orange-and-white chibi cat |
70
+
71
+ > Browse all 1,569+ pets at [**petdex.crafter.run**](https://petdex.crafter.run/)
72
+
73
+ ---
74
+
75
+ ## What Your Pet Does
76
+
77
+ Every Claude Code action triggers a pet reaction:
78
+
79
+ | Claude Code event | Pet animation | Speech bubble |
80
+ |---|---|---|
81
+ | Session starts | Waving | "Let's get to work!" |
82
+ | Reading a file | Review | "Reading filename..." |
83
+ | Editing a file | Idle | "Edited filename" |
84
+ | Running a command | Running | "Running command..." |
85
+ | Searching (Glob/Grep) | Waiting | "Searching..." |
86
+ | Tool fails | Failed | "Oops, something went wrong" + AI encouragement |
87
+ | Task completes | Jumping | "Task complete!" + AI celebration |
88
+ | Claude stops | Jumping | "Task complete!" (60% AI speech) |
89
+ | Claude errors | Failed | Error message + AI comfort |
90
+ | Idle (10+ min) | Waving | Time-aware Chinese greeting |
91
+ | Level up | Current state | "Level up! Kernel!" + all effects activate |
92
+
93
+ ### Pet interactions
94
+
95
+ - **Drag** — click and drag to move your pet anywhere
96
+ - **Right-click** — context menu with Show/Hide, About, Quit
97
+ - **System tray** — right-click the tray icon for menu
98
+ - **Easter egg** — rapidly click your pet for escalating reactions (2 → 4 → 6 → 9 → 12 → 15 clicks)
99
+
100
+ ---
101
+
102
+ ## Level System
103
+
104
+ Your pet levels up based on cumulative Claude Code events. Each level unlocks new visual effects:
105
+
106
+ | Lv | Name | Events | Color | Effect |
107
+ |:---:|---|---:|---|---|
108
+ | 1 | **Byte** | 0 | Silver | Base pet |
109
+ | 2 | **Process** | 50 | Green | Breathing glow |
110
+ | 3 | **Thread** | 200 | Blue | Rotating aura ring |
111
+ | 4 | **Module** | 500 | Purple | Enhanced aura |
112
+ | 5 | **Kernel** | 1,000 | Amber | Floating light particles |
113
+ | 6 | **Neural** | 2,000 | Pink | Particle storm |
114
+ | 7 | **Quantum** | 5,000 | Cyan | Energy field |
115
+ | 8 | **Singularity** | 10,000 | Gold | Golden halo + all effects |
116
+
117
+ ---
118
+
119
+ ## AI Speech
120
+
121
+ When an Anthropic API key is available (auto-detected from Claude Code settings or set via `petdex-cc config`), your pet generates **context-aware speech**:
122
+
123
+ | Scene | Trigger | Example AI response |
124
+ |---|---|---|
125
+ | `task_complete` | Task finishes | "做得好！继续加油！" |
126
+ | `error` | Tool fails | "别担心，bugs难免的~" |
127
+ | `idle` | Idle 10+ minutes | "还在吗？" |
128
+ | `level_up` | Level threshold crossed | "升级啦！太厉害了！" |
129
+
130
+ - **2-minute cooldown** between AI calls (level-ups bypass this)
131
+ - **5-second timeout** — falls back to preset lines if API is slow
132
+ - **No API key?** Built-in preset lines work great — 7 task lines, 5 error lines, 5 idle lines, 4 level-up lines
133
+
134
+ ---
135
+
136
+ ## CLI Reference
137
+
138
+ ```bash
139
+ petdex-cc install <slug> # Download pet, configure hooks, and launch
140
+ petdex-cc start # Start the desktop pet
141
+ petdex-cc stop # Gracefully stop the pet
142
+ petdex-cc list # Browse all pets from Petdex registry
143
+ petdex-cc switch <slug> # Switch pets at runtime (downloads if needed)
144
+ petdex-cc status # Show pet name, level, events, running status
145
+ petdex-cc uninstall # Remove hooks, stop pet, delete all data
146
+ petdex-cc config [options] # Configure settings
147
+ ```
148
+
149
+ ### Config options
150
+
151
+ ```bash
152
+ petdex-cc config --api-key <key> # Anthropic API key for AI speech
153
+ petdex-cc config --api-base-url <url> # API base URL
154
+ petdex-cc config --cooldown <minutes> # AI call cooldown (default: 2)
155
+ ```
156
+
157
+ > API credentials are auto-detected from `~/.claude/settings.json` — most users don't need manual config.
158
+
159
+ ---
160
+
161
+ ## Architecture
162
+
163
+ ```
164
+ ┌─────────────────────────────────────────────────┐
165
+ │ Claude Code │
166
+ │ (tool use, task complete, errors, idle, etc.) │
167
+ └──────────────────────┬──────────────────────────┘
168
+ │ hooks (settings.json)
169
+ ▼
170
+ ┌──────────────────┐
171
+ │ bridge.ps1/.sh │ async, 10s timeout
172
+ └────────┬─────────┘
173
+ │ HTTP POST /event
174
+ ▼
175
+ ┌─────────────────────────────────────────────────┐
176
+ │ petdex-cc (Electron) │
177
+ │ │
178
+ │ ┌──────────────┐ ┌──────────┐ ┌────────────┐ │
179
+ │ │ event-mapper │ │ storage │ │ ai-speech │ │
180
+ │ │ event → action│ │ level, XP │ │ Claude Haiku│ │
181
+ │ └──────┬───────┘ └─────┬────┘ └─────┬──────┘ │
182
+ │ │ │ │ │
183
+ │ └─────────┬───────┘ │ │
184
+ │ ▼ │ │
185
+ │ ┌─────────────────┐ │ │
186
+ │ │ IPC to window │◀─────────────┘ │
187
+ │ └────────┬────────┘ │
188
+ └──────────────────┼──────────────────────────────────┘
189
+ ▼
190
+ ┌──────────────────┐
191
+ │ Pet Window (HTML) │ transparent, always-on-top
192
+ │ │
193
+ │ ┌─── sprite ───┐ │ 9 animation states
194
+ │ │ bubble │ │ 3s / 8s auto-dismiss
195
+ │ │ badge │ │ Lv tag + color
196
+ │ │ effects │ │ glow/aura/particles/halo
197
+ │ └──────────────┘ │
198
+ └──────────────────┘
199
+ ```
200
+
201
+ ---
202
+
203
+ ## Developer Setup
204
+
205
+ ```bash
206
+ git clone https://github.com/devnomad-byte/petdex-cc.git
207
+ cd petdex-cc
208
+ npm install
209
+ npm run build
210
+
211
+ # Run in dev mode
212
+ npx electron .
213
+
214
+ # Install globally for CLI
215
+ npm link
216
+ petdex-cc install boba
217
+ ```
218
+
219
+ ### Project structure
220
+
221
+ ```
222
+ petdex-cc/
223
+ ├── bin/cli.ts CLI entry point (8 commands)
224
+ ├── src/
225
+ │ ├── main/ Electron main process
226
+ │ │ ├── index.ts Window creation, event loop, IPC
227
+ │ │ ├── server.ts HTTP server (hooks → pet, port 17321)
228
+ │ │ ├── ai-speech.ts AI speech via Anthropic Messages API
229
+ │ │ ├── storage.ts HMAC-signed state persistence
230
+ │ │ ├── tray.ts System tray with cat-face icon
231
+ │ │ └── event-mapper.ts 8 hook events → pet actions
232
+ │ ├── renderer/ Electron renderer (pet UI)
233
+ │ │ ├── index.html Transparent window + CSS effects
234
+ │ │ ├── renderer.ts IPC coordination + level effects
235
+ │ │ ├── pet-sprite.ts 9-state spritesheet engine
236
+ │ │ ├── bubble.ts Speech bubble system
237
+ │ │ ├── click-through.ts Transparent click pass-through
238
+ │ │ ├── drag.ts Drag + click easter egg
239
+ │ │ └── context-menu.ts Right-click menu
240
+ │ ├── cli/ CLI command implementations
241
+ │ ├── hooks/ Claude Code hooks (register/unregister)
242
+ │ │ ├── register.ts Writes to ~/.claude/settings.json
243
+ │ │ ├── write-scripts.ts Cross-platform bridge scripts
244
+ │ │ ├── bridge.ps1 Windows PowerShell bridge
245
+ │ │ └── bridge.sh Unix bash bridge
246
+ │ ├── petdex-api/ Petdex registry client
247
+ │ │ ├── client.ts Manifest fetch + slug lookup
248
+ │ │ └── download.ts Streaming download with progress
249
+ │ └── shared/ Shared types and constants
250
+ ```
251
+
252
+ ---
253
+
254
+ ## Configuration Reference
255
+
256
+ ### Auto-detected settings
257
+
258
+ petdex-cc reads these from `~/.claude/settings.json` automatically:
259
+
260
+ | Setting | Used for |
261
+ |---|---|
262
+ | `ANTHROPIC_AUTH_TOKEN` | API key for AI speech |
263
+ | `ANTHROPIC_BASE_URL` | API endpoint for AI speech |
264
+
265
+ ### Manual config
266
+
267
+ Stored in `~/.petdex-cc/config.json`:
268
+
269
+ ```bash
270
+ petdex-cc config --api-key <key> --api-base-url <url> --cooldown 2
271
+ ```
272
+
273
+ ### Data locations
274
+
275
+ | Path | Contents |
276
+ |---|---|
277
+ | `~/.petdex-cc/pets/<slug>/` | Downloaded spritesheet + pet.json |
278
+ | `~/.petdex-cc/data/state.json` | Level, events, pet slug (HMAC-signed) |
279
+ | `~/.petdex-cc/data/state.sig` | HMAC-SHA256 signature |
280
+ | `~/.petdex-cc/hooks/` | Bridge scripts |
281
+ | `~/.petdex-cc/config.json` | User config (API key, cooldown) |
282
+
283
+ ---
284
+
285
+ ## Hooks Reference
286
+
287
+ petdex-cc registers these hooks in `~/.claude/settings.json`:
288
+
289
+ | Hook | Matcher | What triggers it |
290
+ |---|---|---|
291
+ | `PostToolUse` | `Read\|Edit\|Write\|Bash\|Glob\|Grep` | After any tool call |
292
+ | `PostToolUseFailure` | — | After a tool call fails |
293
+ | `Stop` | — | Claude finishes a response |
294
+ | `StopFailure` | — | Claude stops with error |
295
+ | `Notification` | `idle_prompt` | User is idle |
296
+ | `SessionStart` | `startup\|resume` | Claude Code launches or resumes |
297
+ | `SessionEnd` | — | Claude Code session ends |
298
+ | `TaskCompleted` | — | A task is marked complete |
299
+
300
+ ---
301
+
302
+ ## License
303
+
304
+ [MIT](./LICENSE)
305
+
306
+ ---
307
+
308
+ <div align="center">
309
+ <sub>Built for the <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a> community</sub><br />
310
+ <sub>Pets powered by <a href="https://petdex.crafter.run/">Petdex</a></sub>
311
+ </div>