Botflags

A macOS menubar app that drives a Luxafor Flag USB LED to reflect Claude Code session state. The flag breathes orange while Claude is working, holds blue when it's waiting on input, and flashes green when a turn completes.

If you run Claude Code in a pane you aren't watching — or in several at once — Botflags turns its state into a peripheral-vision signal on physical hardware.

Requirements

• macOS 14+
• Xcode 16+
• XcodeGen (brew install xcodegen)
• A Luxafor Flag
• Claude Code

Build

xcodegen generate
open Botflags.xcodeproj

Pick your signing team under Signing & Capabilities and run.

For a standalone .app outside Xcode:

BOTFLAGS_SIGN_ID="Developer ID Application: Your Name (TEAMID)" \
  ./scripts/build-app.sh

Omit BOTFLAGS_SIGN_ID for ad-hoc signing (this Mac only).

On first launch Botflags installs curl-based hooks into ~/.claude/settings.json. Remove them any time with scripts/uninstall-hooks.sh.

How it works

Claude Code hooks
    │  curl --unix-socket /tmp/botflags.sock
    ▼
HookServer  (AF_UNIX, minimal HTTP parser)
    ▼
StateManager  (per-session state + aggregate)
    ▼
Coordinator  (brightness, overrides, animations)
    ▼
Luxafor  (IOKit HID)

Claude Code fires hooks on SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, and SessionEnd. Each posts its payload to a Unix domain socket — not a TCP port — so Botflags never clashes with dev servers you might be running locally.

Multiple concurrent sessions are tracked independently and aggregated; if any one of them is waiting on input, the flag shows blue.

Source layout

Sources/botflags/
├── BotFlagsApp.swift    — @main, MenuBarExtra, menu views, app delegate
├── HookServer.swift     — Unix-socket HTTP listener
├── HookInstaller.swift  — merges hooks into ~/.claude/settings.json
├── HookEvent.swift      — hook payload model
├── StateManager.swift   — per-session state + aggregate
├── Coordinator.swift    — color, brightness, and animation orchestration
├── Luxafor.swift        — IOKit HID driver (VID 0x04D8, PID 0xF372)
└── Brightness.swift     — Low / Medium / High, persisted in UserDefaults

Built on pure Apple frameworks: SwiftUI (MenuBarExtra), AppKit, Combine, IOKit HID, and Darwin sockets. No third-party dependencies.

Menubar

• Brightness — Low / Medium / High.
• Advanced — manual overrides (Thinking, Waiting, Done, Custom color, Off) with a checkmark on the active one, plus "Auto" to resume following session state.
• Hold Option while the menu is open to reveal state and active session count, similar to the macOS Wi-Fi menu.

License

Copyright © 2026 Eduardo Villuendas. Licensed under the GNU General Public License v3.0 — see LICENSE.

This is a strong copyleft license: any derivative work you distribute must also be released under GPL v3 (or a compatible license), with source code available. You are free to use, modify, and redistribute under those terms.