claudeled 1.0.0-alpha

Blinks the Caps Lock LED on your keyboards while a Claude Code session is waiting for
you. Several sessions in several windows aggregate: any one of them waiting is enough
to light the lamp.

It writes to the keyboard's LED element directly, so the Caps Lock modifier is
never asserted and your typing case is unaffected.

This release adds two things the beta could not do: it can tell you where your time
went, and the lamp can be told to give up.

What's new since 0.9.0-beta

Statistics

The hooks that already blink the lamp now also append one line each to
~/.config/claudeled/events/YYYY-MM.jsonl. Every pair of consecutive events brackets a
gap, and the earlier event says what was happening during it: after prompt Claude was
working, after stop it was waiting on you, after notify it was blocked on a
permission prompt.

today      worked 1h 12m · waiting on you 34m · blocked 2m
this week  worked 8h 03m · waiting on you 3h 41m

project      worked   waiting
topscan       5h 20m    2h 10m
claudeled     2h 43m    1h 31m

12 sessions this week · 4h 12m skipped as away (gaps over 5m)

claudeled stats                       today and the last 7 days
claudeled stats week|month|year|all   one window instead of two
claudeled stats -i                    pick a period and a destination with the arrows
claudeled stats month --md            a markdown table, for pasting
claudeled stats week --json           the same numbers, for scripts
claudeled stats all --card [file]     a PNG card, for sharing

The menu has the same thing under Statistics…, with Copy as Markdown and
Save PNG Card…. The arrow-key picker only appears when both ends are a terminal, so
claudeled stats --json | jq is never interrupted by a menu.

Gaps longer than five minutes are reported as away rather than counted — you went to
lunch, and no honest number tells that apart from thinking hard. Change the threshold
with "idleCapSeconds" in ~/.config/claudeled/config.json.

Only the last component of the working directory is ever stored, never the full path,
so sharing a report does not leak where your work lives.

A blink timeout

The lamp can now stop on its own. Blink for in the menu offers 5 min, 10 min, 30 min
and Always; the CLI takes any duration:

claudeled blink            # show the current setting
claudeled blink 10m        # also 5m, 90s, 1h, 600, or always

Both write the same config, and the running app picks the change up within a second —
nothing needs restarting.

The default is Always, which is exactly what the beta did, so upgrading changes
nothing until you ask it to. Timing out is about the light only: the session is still
waiting, the menu and claudeled status still count it, and the next thing Claude does
re-arms the timer.

Under the hood

The source is split into Core/, which imports neither AppKit nor IOKit and is what
the tests compile against, and App/, the shell around it. 105 assert-based checks,
no framework and no fixtures. The README was rewritten against the actual code.

Install

Download claudeled-1.0.0-alpha.zip, unzip, move claudeled.app to /Applications,
then clear the quarantine flag:

xattr -dr com.apple.quarantine /Applications/claudeled.app
open /Applications/claudeled.app

Without that, macOS refuses to open it: the app is ad-hoc signed rather than notarised,
and anything arriving through a browser is quarantined. The alternative is to launch it,
let it be blocked, and allow it in System Settings → Privacy & Security → Open Anyway.

Or build it yourself and skip Gatekeeper entirely:

git clone https://github.com/odiumuniverse/claudeled && cd claudeled && make install

Upgrading from 0.9.0-beta needs nothing extra. Your config and your event log are kept,
and the hooks are re-pointed at the new bundle on first launch.

First launch

It installs its Claude Code hooks into ~/.claude/settings.json — merged, leaving your
other hooks alone — and asks for Input Monitoring, which macOS requires before any
process may touch a keyboard's LED. Grant it and the app restarts itself.

Requirements

macOS 13 Ventura or newer.

Checksums

SHA256  82d26ae97c29c81ff0ea40a6516ebb6fffc4fa9f8ddc169f81d07316c4692ca8  claudeled-1.0.0-alpha.zip
SHA256  d4fd44604863fb6feb0babbbd96429cd240b16e60d3b3a1b43103d9954b28f80  Source code (tar.gz)
SHA256  0a493a37f77e5b428ec4ca72f9e59f96361d9b31863bb635112e1e4df5e3364b  Source code (zip)

Verify the download before you unzip it:

shasum -a 256 claudeled-1.0.0-alpha.zip

The two Source code lines are the archives GitHub generates from the tag. They are
recorded here for completeness; GitHub regenerates them on demand, so treat the tag
itself as the authority if a sum ever fails to match.

Known limitations

This is an alpha.

• Ad-hoc signed, not notarised, so every download needs the quarantine step above.
• Verified on the MacBook internal keyboard (SPI) and Magic Keyboard 2 (Bluetooth).
  Other keyboards are handled generically — if one exposes a Caps Lock LED element it
  can be driven, and claudeled test <name> tells you in three seconds.
• Rebuilding from source changes the ad-hoc signature, which voids the Input Monitoring
  grant. make install clears the stale grant so macOS asks again.
• The statistics only know what the hooks logged, so they start counting from the
  moment you install this build — there is no history to backfill from.