clawd-buddy 0.1.0__tar.gz

clawd_buddy-0.1.0/.claude/commands/buddy.md

@@ -0,0 +1,23 @@
+# Clawd Buddy commands
+
+Clawd Buddy — manage the animated taskbar companion.
+
+Usage: /buddy [action]
+
+Actions:
+  start    — Launch the buddy on the taskbar (if not already running)
+  stop     — Kill the running buddy
+  test     — Send a test celebration to the running buddy
+  wave     — Send a wave/attention signal to the running buddy
+  status   — Check if the buddy is running
+
+If no action is given, default to "start".
+
+Implementation:
+
+- `clawd-buddy` is installed globally via `uv tool install`
+- For "start": run `clawd-buddy` in the background (detached)
+- For "stop": find the buddy process via `netstat -ano | findstr 44556` to get the PID, then `taskkill /F /PID <pid>`
+- For "test": run `clawd-buddy --send "Test!"`
+- For "wave": run `clawd-buddy --wave`
+- For "status": check if port 44556 is in use via `netstat -ano | findstr 44556`

clawd_buddy-0.1.0/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "clawd-buddy --send done",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "clawd-buddy --wave",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}

clawd_buddy-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+venv/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+Thumbs.db
+Desktop.ini
+.DS_Store
+
+# Env
+.env
+.env.local

clawd_buddy-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to Clawd Buddy will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-04-13
+
+### Added
+
+- Initial release
+- Animated terminal character with idle, celebrate, and wave states
+- Borderless transparent window positioned on the Windows taskbar
+- Click-and-drag repositioning
+- TCP socket listener (port 44556) for receiving signals
+- `--send` flag to trigger celebration on a running instance
+- `--wave` flag to trigger wave/attention animation
+- `--test` flag to start with a celebration
+- `--port` flag for custom TCP port
+- `--no-topmost` flag to disable always-on-top
+- `--startup` flag to enable run at Windows login
+- `--no-startup` flag to disable run at Windows startup
+- Single-instance enforcement via lock socket
+- System tray icon with context menu
+- Claude Code hook support (`Stop` and `PermissionRequest` events)
+- Confetti particle system during celebrations
+- Floating pulsing "!" indicator during wave state
+- Hidden console window when started via startup launcher

clawd_buddy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to Clawd Buddy
+
+Thanks for your interest in contributing!
+
+## Development setup
+
+```bash
+git clone https://github.com/ramymagdy-rm/clawd-buddy.git
+cd clawd-buddy
+
+# Create a venv and install in editable mode
+uv venv
+uv pip install -e ".[dev]"
+
+# Or with pip
+python -m venv venv
+venv\Scripts\activate
+pip install -e .
+```
+
+## Running locally
+
+```bash
+# Run from source
+python -m clawd_buddy.app
+
+# Or if installed in editable mode
+clawd-buddy
+```
+
+## Project structure
+
+```text
+clawd-buddy/
+├── src/clawd_buddy/
+│   ├── __init__.py       # Package metadata
+│   └── app.py            # All application code (rendering, state, socket, tray)
+├── .claude/
+│   ├── settings.json     # Claude Code hook definitions
+│   └── commands/
+│       └── buddy.md      # /buddy slash command for Claude Code
+├── pyproject.toml        # Package configuration
+├── README.md
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+└── LICENSE
+```
+
+## How the code is organized
+
+Everything lives in `app.py` to keep the package simple:
+
+- **Win32 helpers** — `ctypes` calls for transparency, positioning, taskbar detection
+- **State machine** — `BuddyState` with three modes: `idle`, `celebrating`, `waving`
+- **Drawing** — `draw_buddy()` renders the character based on current state and time
+- **Socket listener** — TCP server on port 44556, parses JSON `{"action": "..."}` messages
+- **System tray** — `pystray` icon with context menu
+- **CLI** — `argparse` for `--send`, `--wave`, `--test`, `--startup`, etc.
+- **Main loop** — pygame event loop at 60 FPS
+
+## Making changes
+
+1. Fork the repo and create a feature branch
+2. Make your changes in `src/clawd_buddy/app.py`
+3. Test manually: `clawd-buddy --test` (celebrate), `clawd-buddy --wave` (wave signal)
+4. Update `CHANGELOG.md` under an `[Unreleased]` section
+5. Open a pull request
+
+## Adding a new animation state
+
+1. Add the state name to `BuddyState` (add a property and trigger method)
+2. Add drawing logic in `draw_buddy()` — follow the pattern of `cel`/`wav` branches
+3. Add a new action string in `socket_listener()` dispatch
+4. Add a CLI flag in `parse_args()` and handle it in `main()`
+5. Document the new hook in `README.md`
+
+## Guidelines
+
+- Keep everything in `app.py` unless there's a strong reason to split
+- No external assets — all rendering is procedural (pygame draw calls)
+- Windows-only is fine for now; cross-platform support would need platform abstraction for the win32 calls
+- Test all three states (idle, celebrate, wave) after any drawing changes

clawd_buddy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramy Ezzat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clawd_buddy-0.1.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: clawd-buddy
+Version: 0.1.0
+Summary: Animated terminal pet that sits on your taskbar and reacts to AI coding assistant events
+Project-URL: Homepage, https://github.com/ramymagdy-rm/clawd-buddy
+Project-URL: Repository, https://github.com/ramymagdy-rm/clawd-buddy
+Project-URL: Issues, https://github.com/ramymagdy-rm/clawd-buddy/issues
+Author-email: Ramy Magdy <ramymagdy-rm@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: animation,buddy,clawd,coding-assistant,pet,taskbar
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.0
+Requires-Dist: pygame-ce>=2.5
+Requires-Dist: pystray>=0.19
+Description-Content-Type: text/markdown
+
+# Clawd Buddy
+
+A tiny animated terminal pet that sits on your Windows taskbar and reacts to [Claude Code](https://claude.ai/code) events.
+
+<!-- TODO: add a gif/screenshot here -->
+<!-- ![Clawd Buddy demo](docs/demo.gif) -->
+
+## What it does
+
+Clawd Buddy is a small always-on-top character that lives on your taskbar while you work with Claude Code:
+
+| State | What happens |
+| --- | --- |
+| **Idle** | Gently bobs, blinks, breathes — your quiet companion |
+| **Assistant finishes** (`Stop` hook) | Celebrates with confetti, happy eyes, and waving arms |
+| **Assistant needs permission** (`PermissionRequest` hook) | Waves at you with a floating **!** so you know to check back |
+
+## Install
+
+```bash
+# With uv (recommended — installs as an isolated tool)
+uv tool install clawd-buddy
+
+# With pipx
+pipx install clawd-buddy
+
+# With pip (into current environment)
+pip install clawd-buddy
+```
+
+### From source
+
+```bash
+git clone https://github.com/ramymagdy-rm/clawd-buddy.git
+cd clawd-buddy
+uv tool install --from . clawd-buddy
+```
+
+## Quick start
+
+### 1. Launch the buddy
+
+```bash
+clawd-buddy
+```
+
+The buddy appears on your taskbar, centered at the bottom of the screen. It runs until you close it.
+
+### 2. Run at startup (optional)
+
+```bash
+# Enable — buddy starts automatically when you log into Windows
+clawd-buddy --startup
+
+# Disable — remove from startup
+clawd-buddy --no-startup
+```
+
+This places a lightweight launcher in your Windows Startup folder (`shell:startup`). No console window appears — the buddy runs silently in the background.
+
+### 3. Wire up Claude Code hooks
+
+Add to your **global** Claude Code settings (`~/.claude/settings.json`) so every session triggers the buddy:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "clawd-buddy --send done",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "clawd-buddy --wave",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+> **Note:** If you already have other hooks in your `settings.json`, merge the `Stop` and `PermissionRequest` entries into the existing `hooks` object.
+
+### 4. Done
+
+Start a Claude Code session anywhere. When the assistant finishes or needs your attention, the buddy reacts.
+
+## CLI reference
+
+```text
+clawd-buddy                  Start buddy on taskbar
+clawd-buddy --test           Start with a celebration animation
+clawd-buddy --send MSG       Signal a running buddy to celebrate
+clawd-buddy --wave           Signal a running buddy to wave (needs attention)
+clawd-buddy --startup        Enable run at Windows startup
+clawd-buddy --no-startup     Disable run at Windows startup
+clawd-buddy --port PORT      Use a custom TCP port (default: 44556)
+clawd-buddy --no-topmost     Don't keep the window always-on-top
+clawd-buddy --help           Show help
+```
+
+## Controls
+
+| Input | Action |
+| --- | --- |
+| **Drag** | Click anywhere on the buddy and drag to reposition |
+| **Space** | Trigger a test celebration |
+| **Escape** | Quit the buddy |
+| **Tray icon** | Right-click the system tray icon for a menu |
+
+## How it works
+
+### Architecture
+
+```text
+Claude Code                            Clawd Buddy
+-----------                            -----------
+ hooks/Stop ──> clawd-buddy --send ──> TCP:44556 ──> celebrate animation
+ hooks/PermissionRequest ──> clawd-buddy --wave ──> TCP:44556 ──> wave animation
+```
+
+1. **Claude Code hooks** fire shell commands when events happen (response done, permission needed).
+2. The `clawd-buddy --send` / `--wave` CLI connects to `127.0.0.1:44556` and sends a JSON action.
+3. The running buddy process receives the signal and plays the animation.
+
+### Signal protocol
+
+The buddy listens on a TCP socket (default port `44556`). Send a JSON payload to trigger actions:
+
+```json
+{"action": "celebrate"}
+```
+
+```json
+{"action": "wave"}
+```
+
+You can send signals from any language:
+
+```python
+import socket, json
+s = socket.socket()
+s.connect(("127.0.0.1", 44556))
+s.sendall(json.dumps({"action": "celebrate"}).encode())
+s.close()
+```
+
+```bash
+echo '{"action": "wave"}' | nc localhost 44556
+```
+
+### Single instance
+
+Only one buddy can run at a time. If you launch `clawd-buddy` while one is already running, it sends a signal to the existing instance and exits.
+
+### System tray
+
+The buddy adds a system tray icon with a right-click menu:
+
+- **Test Celebration** — trigger the celebrate animation
+- **Quit** — close the buddy
+
+### Windows startup
+
+`clawd-buddy --startup` places a small VBS launcher in your Windows Startup folder:
+
+```text
+%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\clawd-buddy-startup.vbs
+```
+
+This script starts the buddy with a hidden console window. To remove it, run `clawd-buddy --no-startup` or delete the file manually.
+
+## Animations
+
+### Idle
+
+- Gentle vertical bobbing (sine wave)
+- Periodic blinking (every ~3.5 seconds)
+- Pupils wander slowly
+- Small mouth line with subtle movement
+- Arms sway gently at sides
+
+### Celebrate (on `Stop`)
+
+- Fast bouncing
+- Happy arc eyes (^ ^)
+- Wide smile
+- Both arms waving up
+- Legs kicking
+- Confetti burst (40 particles with gravity and drag)
+- Duration: 3.5 seconds
+
+### Wave (on `PermissionRequest`)
+
+- Medium bobbing
+- Wide alert eyes (large pupils, staring)
+- Surprised "o" mouth
+- Right arm waving high
+- Pulsing floating **!** indicator above head
+- Duration: 5 seconds
+
+## Configuration
+
+### Custom port
+
+If port `44556` is taken, use a different one:
+
+```bash
+clawd-buddy --port 55000
+```
+
+Update your hooks to match:
+
+```json
+"command": "clawd-buddy --send done --port 55000"
+```
+
+### Disable always-on-top
+
+```bash
+clawd-buddy --no-topmost
+```
+
+## Troubleshooting
+
+### Buddy doesn't appear
+
+- **Windows only**: Clawd Buddy uses Windows-specific APIs (`user32`, `shell32`) for transparency and taskbar detection. It does not work on macOS or Linux.
+- Make sure no other process is using port `44556`: `netstat -ano | findstr 44556`
+
+### Hook doesn't trigger the buddy
+
+- Make sure the buddy is running (`clawd-buddy` in a terminal or via `--startup`).
+- Test manually: `clawd-buddy --send test` — if this says "No buddy on port 44556", the buddy isn't running.
+- Check that `clawd-buddy` is on your PATH: `where clawd-buddy`
+
+### Multiple buddies / port conflict
+
+- The buddy uses a lock socket on port `44557` (main port + 1) to prevent duplicates.
+- If a stale lock is stuck, kill the process and restart: `taskkill /F /IM clawd-buddy.exe`
+
+### Startup not working
+
+- Verify the VBS file exists: `dir "%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\clawd-buddy*"`
+- Re-run `clawd-buddy --startup` to regenerate it.
+- Make sure `clawd-buddy.exe` is on your PATH: `where clawd-buddy`
+
+## Disclaimer
+
+Clawd Buddy is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic, PBC.
+
+## License
+
+[MIT](LICENSE)