CodeIsland

Buddy is a hardware peripheral for CodeIsland that brings the AI Coding Agent status animations from the macOS Dynamic Island to a physical ESP32-powered small screen on your desk.

It uses Bluetooth Low Energy (BLE) to receive real-time status updates from the macOS CodeIsland application and displays corresponding pixel mascot animations based on the agent's state:

• Idle $\rightarrow$ Sleep: Mascot sleeps with eyes closed.
• Processing / Running $\rightarrow$ Work: Mascot is coding.
• Wait Approval $\rightarrow$ Alert: Mascot calls for your attention.
• Wait Question $\rightarrow$ Question: Mascot prompts you to answer a question.

When not connected via BLE, Buddy displays a guidance page with the project's GitHub QR code and the device name. You can enter Demo Mode by long-pressing the button to automatically cycle through all 16 mascots.

CodeIsland Buddy Watch is a Wear OS companion app designed to mirror the hardware/Buddy protocol used by CodeIsland. It functions as a BLE (Bluetooth Low Energy) peripheral named Buddy, making it discoverable by the macOS application.

Key capabilities include:

• Mirroring mascot, agent status, tool name, brightness, and orientation frames.
• Support for both square and round watch screens.
• Screen interaction: Tap to notify the host with the current mascot sourceId; long-press to toggle local demo mode.

CodeIsland Buddy Watch is the Wear OS implementation for CodeIsland. It acts as a BLE peripheral broadcasting under the name Buddy, allowing it to be scanned and connected to by the macOS client.

Key Features:

• Synchronizes mascot, Agent status, tool name, brightness, and screen orientation.
• Supports both square and round watch faces via resource qualifiers.
• Tap screen: Sends the current mascot's sourceId back to the host.
• Long press: Toggles between a local demo mode and Agent mode (Agent mode resumes automatically upon receiving a new real-time frame).

The Waveshare ESP32-C6-LCD-1.47 development board uses the ESP32-C6FH4 microcontroller. Key hardware features include:

• Wireless: 2.4GHz Wi-Fi 6 and BLE 5.
• Storage: 4MB Flash.
• Display: 1.47" TFT, 172x320 resolution, driven by the ST7789 driver.
• Peripherals: Onboard Micro SD, RGB LED, BOOT button, and RESET button.

The Code Island Buddy Xcode project is organized into several targets and shared modules:

• CodeIslandCompanion/: The main iPhone application.
• CodeIslandCompanionWidget/: Provides the iPhone Live Activity, Dynamic Island, and StandBy UI.
• CodeIslandWatchApp/: The Apple Watch application.
• CodeIslandWatchWidget/: The watchOS widget.
• Shared/: Contains shared models, display helpers, and mascot views used across targets.
• project.yml: The XcodeGen project definition file used to generate the .xcodeproj.

To prevent silent reinstallation of agents that a user has explicitly uninstalled, implement an AgentIntentStore using a tri-state model. This ensures the 'source of truth' for an agent's status is managed centrally rather than being split between settings, disk state, and actual installation.

The AgentHookIntent Model:

• untouched: The agent has never been interacted with; the app can suggest installation.
• installed: The user chose to install; the app should verify and repair on startup.
• uninstalled: The user explicitly chose to uninstall; the app must not touch or reinstall it during startup.

Implementation Details:

• Use UserDefaults with a stable key pattern: agentIntent.<rawValue>.
• Implement a migrationVersion to handle first-time upgrades (e.g., scanning existing hooks and setting them to installed without triggering onboarding).

When using git worktree, the current working directory (CWD) often contains paths like ~/code/foo/.git/worktrees/feat-bar. To ensure session cards display meaningful names, implement a WorkspaceNameResolver to map these paths back to the project and branch names.

Resolution Logic:

1. Identify markers for /.claude/worktrees/ or /.git/worktrees/.
2. Extract the last path component before the marker as the Project Name.
3. Convert the path components after the marker from + back to / to reconstruct the Branch Name (since git worktree replaces / with + in paths).
4. Format the display as: "<projectName> (<branch>)".

Buddy is specifically designed for the following hardware configuration. Using other boards may require significant modifications.

Note on Buttons: The onboard BOOT button is repurposed as the main functional button (GPIO9). No external buttons are required. Short presses switch mascots, and long presses enter Demo Mode.

The system uses a dual-channel communication strategy to balance full state synchronization with background reliability without requiring a backend or APNs:

• MultipeerConnectivity: Used for full state synchronization, recent activities, and sending operation commands. This is best suited for when the iPhone app is in the foreground.
• CoreBluetooth (BLE): Used for transmitting lightweight status summaries (e.g., agent name, status, current message, workspace). This allows the iPhone to refresh Live Activities and update the Apple Watch even when the app is in the background or on the lock screen.
• WatchConnectivity: Synchronizes the current iPhone state to the paired Apple Watch.

Communication Flow:

• Mac CodeIsland $\rightarrow$ (Multipeer/BLE) $\rightarrow$ iPhone $\rightarrow$ (WatchConnectivity) $\rightarrow$ Apple Watch.