PixelClaw

Product Introduction

1. Definition: PixelClaw is an open-source, macOS-native desktop companion and "virtual pet" application built using Swift and AppKit. Categorized as a desktop enhancement utility, it features a pixel-art crab that resides specifically on the macOS Dock, utilizing system accessibility APIs to interact with the user's workspace in real-time.

2. Core Value Proposition: PixelClaw was developed to mitigate the "wait-time fatigue" experienced by software engineers and developers using long-running background processes, such as Claude Code or CI/CD pipelines. By providing a charming, interactive pixel-art distraction, it improves the developer experience (DX) during idle periods. Key keywords associated with its value include Mac Dock pet, pixel art animation, developer productivity companion, and Swift-based desktop widget.

Main Features

1. Dynamic Dock-Aware Positioning: PixelClaw leverages macOS Accessibility permissions to programmatically determine the precise coordinates and orientation of the Mac Dock. This ensures the animated crab remains pinned to the user's interface regardless of Dock size, position (bottom, left, or right), or magnification settings. The application uses specialized Dock geometry helpers within its source code to maintain visual consistency.

2. State-Based Animation Engine: The application features a sophisticated animation loop that manages multiple behavioral states, including napping, waking, hopping, and chasing. Built with Swift 5.9 and AppKit drawing logic, the sprite-based system renders high-quality pixel art with low CPU overhead. The crab transitions between these states based on user interaction or idle timers, creating a lifelike "living" feel on the screen.

3. Interactive Physics and Input Handling: Users can trigger specific behaviors through a combination of global hotkeys and mouse events. By pressing Option+F, the app executes a "drop apple" function, which spawns an interactive sprite that the crab identifies as a target. The interaction logic includes click-detection for waking the pet, making it hop, or tossing apples, all managed through a dedicated application state controller in the Sources/PixelClaw/App directory.

Problems Solved

1. Developer Idle Boredom: Many modern development workflows involve waiting for AI agents like Claude Code to finish complex tasks. PixelClaw addresses the psychological "dead time" by providing a non-intrusive, visually appealing micro-interaction that reduces the urge to context-switch to distracting websites.

2. Target Audience: The primary personas include macOS Power Users, Software Engineers using CLI-based AI tools, AppKit/Swift Developers interested in desktop UI manipulation, and Pixel Art enthusiasts. It specifically appeals to those who spend significant time in terminal environments and want to "humanize" their digital workspace.

3. Use Cases: Ideal for monitoring long-running terminal commands, waiting for software builds to compile, or as a lightweight desktop decoration for creative professionals who appreciate retro-style pixel aesthetics.

Unique Advantages

1. Lightweight Native Performance: Unlike many modern desktop widgets built on Electron or web technologies, PixelClaw is written natively in Swift. This ensures minimal RAM usage and high energy efficiency, which is critical for developers who need to preserve system resources for heavy compilation tasks.

2. Open-Source Transparency: Hosted on GitHub under the MIT License, PixelClaw allows users to audit the code, which is particularly important given that the app requires Accessibility permissions. This transparency builds trust compared to closed-source desktop pets.

3. Seamless Installation Ecosystem: PixelClaw offers professional-grade distribution methods, including a Homebrew tap (brew install masasron/tap/pixelclaw) and a standardized Makefile for building DMG files or app bundles. This makes it highly accessible for users familiar with the macOS developer ecosystem.

Frequently Asked Questions (FAQ)

1. Why does PixelClaw require Accessibility permissions on macOS? PixelClaw requires Accessibility access specifically to read the geometry and screen position of the macOS Dock. Without these permissions, the app cannot "sit" on top of the Dock or respond correctly to its movements and resizing. Users can manage this in System Settings > Privacy & Security > Accessibility.

2. How do I interact with the pixel crab and drop apples? Interaction is handled through both keyboard and mouse. You can drop an apple for the crab to chase by pressing Option+F. Additionally, clicking the crab while it sleeps will wake it up, and clicking it while it is awake will trigger a "hop" animation. You can also click an existing apple to "toss" it to a new location.

3. Can I build PixelClaw from source if I don't want to use the DMG? Yes, PixelClaw is fully compatible with the Swift Package Manager. Developers can clone the repository and run swift run PixelClaw or use the provided make commands. It requires macOS 12 or later and the Swift 5.9+ toolchain (included with modern versions of Xcode).