Listen to this Post
Introduction:
As AI-powered coding assistants like Claude Code become indispensable in development workflows, developers face a growing challenge: maintaining awareness of agent activity without constantly switching context to a terminal window. This visibility gap creates friction, interrupts flow states, and reduces productivity. The claude-lamp project—developed by Bobek Balinek and recently spotlighted by Charly Wargnier—solves this problem through an ingenious integration of Claude Code’s hook system with Bluetooth Low Energy (BLE)-enabled Moonside lamps. By transforming a physical desk lamp into a real-time status indicator, this open-source tool provides instant visual feedback on AI agent states, enabling developers to stay immersed in their work while maintaining complete situational awareness of their AI assistant’s activity.
Learning Objectives:
- Understand the architecture and event-driven hook system that enables real-time communication between Claude Code and physical IoT devices
- Master the setup and configuration of BLE-enabled lamps as visual status indicators for AI coding assistants
- Learn to customize state-to-color mappings and extend the integration to other BLE-compatible devices
- Understanding the Claude Hook Ecosystem and Event-Driven Architecture
The claude-lamp project leverages Claude Code’s comprehensive hook system, which intercepts key events throughout the AI agent’s lifecycle. When Claude Code transitions between states—processing a prompt, executing tools, awaiting user input, or completing a response—it triggers corresponding hooks that communicate these state changes to external scripts.
The architecture employs a three-tier design:
- Hook scripts (
moonside_hook.sh): Shell scripts called by Claude Code that write state information to a temporary file (/tmp/moonside_state) and launch the daemon if needed - Persistent daemon (
moonside_daemon.py): A background Python process maintaining a constant BLE connection to the lamp, reading the state file every 200ms to eliminate 2-5 second reconnection latency - BLE controller (
moonside_ble.py): Standalone utility for direct lamp control, useful for testing and manual overrides
This separation ensures that hook execution remains fast and non-blocking while the daemon handles the potentially slower BLE communication. The daemon includes intelligent debouncing to prevent phantom transitions—for example, filtering out internal prompt suggestions that might fire PreToolUse events shortly after a Stop event.
2. Prerequisites and Hardware Requirements
Before diving into the setup, ensure your environment meets these requirements:
Hardware:
- A Moonside LED lamp (tested with Halo model; compatible with One, Aurora, Lighthouse, and similar models)
- A macOS system with BLE (CoreBluetooth) support
Software:
- Python 3.10 or higher
- Claude Code installed and configured
- The `bleak` Python library for BLE communication: `pip install bleak`
Network Considerations:
- BLE operates locally; no internet connection is required beyond initial Claude Code usage
- The daemon automatically discovers lamps by name—no MAC address configuration needed for single-lamp setups
3. Step-by-Step Installation and Configuration
The installation process follows a straightforward four-step workflow:
Step 1: Install the bleak library
pip install bleak
This library handles all BLE communication with the Moonside lamp.
Step 2: Create the hooks directory and copy scripts
mkdir -p ~/.claude/moonside_hooks cp claude_hooks/moonside_hook.sh claude_hooks/moonside_daemon.py ~/.claude/moonside_hooks/ chmod +x ~/.claude/moonside_hooks/moonside_hook.sh
Placing scripts in `~/.claude/moonside_hooks/` ensures they work across all projects without requiring the hooks folder in every repository.
Step 3: Merge hook configuration into Claude settings
The configuration file (claude_hooks/settings.json) needs to be merged into ~/.claude/settings.json. Update the paths from `$CLAUDE_PROJECT_DIR/claude_hooks` to ~/.claude/moonside_hooks/:
sed 's|\$CLAUDE_PROJECT_DIR/claude_hooks|~/.claude/moonside_hooks|g' \ claude_hooks/settings.json
Alternatively, manually copy the JSON and replace paths. The configuration hooks into the following events: SessionStart, UserPromptSubmit, Stop, `PreToolUse` (all tools), PostToolUse, PermissionRequest, Notification, and SessionEnd.
Step 4: Restart Claude Code
Open a new Claude Code session. The daemon auto-discovers your lamp by name—no address configuration needed. For multiple lamps, set the `MOONSIDE_MAC` environment variable to pin a specific device:
python3 moonside_ble.py scan List available devices export MOONSIDE_MAC="your-device-uuid"
On macOS, addresses are UUIDs, not MAC addresses.
4. Daemon Lifecycle and State Management
Understanding the daemon’s lifecycle helps with troubleshooting and customization:
Key Files:
- PID file:
/tmp/moonside_daemon.pid—stores the daemon’s process ID - State file:
/tmp/moonside_state—contains the current lamp state (working, idle, input, off) - Log file:
/tmp/moonside_daemon.log—debugging and error information
Lifecycle Behaviors:
- The daemon launches automatically when the first hook event occurs
- It maintains a persistent BLE connection to avoid reconnection latency on every event
- Auto-exits after 30 minutes of inactivity or on `SessionEnd` events
- The hook script always exits with code 0 (success), ensuring it never blocks Claude Code execution
State Mapping:
| State | Visual Effect | Trigger |
|-|||
| Working | BEAT2 theme (white/navy) | Prompt submit, tool use |
| Idle | Solid sunset mango (255, 180, 50) | Claude finishes responding, session start |
| Needs Input | Solid purple (200, 0, 255) | Permission request, plan approval, question, notification |
| Off | LED off | Session end |
5. Standalone BLE Control and Advanced Customization
The `moonside_ble.py` script can be used independently of Claude Code for direct lamp control and testing:
Basic Commands:
python3 moonside_ble.py scan Find BLE devices python3 moonside_ble.py on Turn lamp on python3 moonside_ble.py off Turn lamp off python3 moonside_ble.py color 255 0 128 Set RGB color python3 moonside_ble.py color 255 0 128 --brightness 80 python3 moonside_ble.py theme rainbow3 Activate a theme python3 moonside_ble.py theme fire2 --colors 255,50,0 python3 moonside_ble.py raw "THEME.GRADIENT1.255,0,0,0,0,255" python3 moonside_ble.py interactive REPL mode for experimentation
Customizing State Colors:
Default colors are configured in moonside_daemon.py. To modify them:
1. Locate the color configuration section in the daemon script
2. Adjust RGB values for working, idle, and input states
3. Restart the daemon or wait for auto-restart
BLE Protocol Details:
Moonside lamps use the Nordic UART Service (NUS) over BLE with ASCII text commands:
| Command | Format | Example |
||–||
| LED on/off | `LEDON` / `LEDOFF` | `LEDOFF` |
| Color (0-255) | `COLORRRRGGGBBB` | `COLOR000255000` |
| Brightness (0-120) | `BRIGHBBB` | `BRIGH060` |
| Theme | `THEME.NAME.R,G,B,…` | `THEME.FIRE2.255,50,0` |
6. Troubleshooting Common Issues
Lamp Not Responding:
Check daemon logs for errors cat /tmp/moonside_daemon.log Verify BLE connection works independently python3 moonside_ble.py on
Daemon Stuck:
kill "$(cat /tmp/moonside_daemon.pid)" rm -f /tmp/moonside_daemon.pid /tmp/moonside_state
bleak Not Found:
The hook auto-detects Python from python3, /opt/homebrew/bin/python3, and $CONDA_PREFIX/bin/python3. Ensure one of these has bleak installed:
python3 -m pip install bleak
Connection Handshake Delays:
The initial connection handshake may take a few seconds. Tail the daemon logs to verify everything works fine:
tail -f /tmp/moonside_daemon.log
7. Security, Privacy, and Operational Considerations
Local-Only Communication: All BLE communication occurs locally between your machine and the lamp. No data is transmitted over the internet, ensuring that AI agent activity indicators remain private and secure.
No API Keys or Tokens: The integration requires no additional API keys, cloud services, or third-party authentication. It operates purely on local BLE protocols.
Permission Model: Claude Code’s hook system runs with the same permissions as your Claude Code session. The lamp control scripts do not require elevated privileges beyond standard user access to BLE hardware.
Hardware Risk Warning: The author explicitly notes: “Author takes no responsibility for the hardware issues that may arise from using this script. You run these scripts at your own risk”. While the BLE protocol is standard, continuous communication patterns may affect lamp longevity—users should monitor lamp behavior and adjust configurations if overheating or unusual behavior occurs.
What Undercode Say:
- Key Takeaway 1: The claude-lamp project demonstrates how AI agent state awareness can be offloaded from screens to physical spaces, reducing cognitive load and context switching during development sessions.
- Key Takeaway 2: The event-driven hook architecture provides a reusable pattern for integrating Claude Code with any IoT device—from RGB keyboards to notification systems—enabling creative physical computing applications for AI-assisted workflows.
The integration represents a significant step toward ambient computing in AI development environments. Rather than forcing developers to constantly check terminals or dashboards, physical indicators provide peripheral awareness that maintains flow states. This approach aligns with research showing that environmental cues reduce interruption costs and improve task performance in knowledge work. The open-source nature of the project (MIT license) encourages community contributions and adaptations, potentially spawning a ecosystem of physical AI status indicators.
Prediction:
- +1 Physical computing integrations with AI coding assistants will become standard practice within 18-24 months, with major AI vendors offering official IoT device support and SDKs.
- +1 The hook-based event model demonstrated by this project will influence how AI assistants expose state information, leading to standardized webhook and MQTT interfaces for ambient computing applications.
- -1 Hardware compatibility fragmentation—with different lamp models using proprietary BLE protocols—may slow widespread adoption until universal standards emerge or community reverse-engineering efforts mature.
- +1 Enterprise AI development environments will adopt similar physical indicators for team awareness, showing when shared AI agents are busy, idle, or awaiting input across multiple users.
- -1 The reliance on macOS and specific BLE hardware limits accessibility; cross-platform support (Windows, Linux) and virtual/software-based indicators will be necessary for broader adoption.
▶️ Related Video (78% Match):
🎯Let’s Practice For Free:
🎓 Live Courses & Certifications:
Join Undercode Academy for Verified Certifications
🚀 Request a Custom Project:
Secure, high-velocity infrastructure and disruptive technological engineering. Contact our engineering team for high-tier development and proprietary systems:
[email protected]
💎 Smart Architecture | 🛡️ Secure by Design | ⭐ Trusted by Thousands
IT/Security Reporter URL:
Reported By: Charlywargnier This – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
