PlugLight
Your MagSafe cable is now a status light for AI coding agents.
See at a glance whether Claude Code, Codex CLI, Cursor or any of the other five supported agents is working, waiting for you, or done — right on the charging cable.
English · Українська
| LED | Meaning |
|---|
| Working — the agent is running |
| Waiting for you — permission prompt or a question |
| Error — the turn failed |
| Done — for 10 minutes, then back to normal |
| No active sessions — macOS shows charging as usual |
With several agents running, the most important state wins: error › waiting › working › done.
The hardware can only do green, orange and off, so that is the whole palette.
Install
curl -fsSL https://raw.githubusercontent.com/onelenyk/pluglight/main/get.sh | sh
This downloads the latest release, verifies its checksum, puts PlugLight in Applications and starts it. On first launch it offers to:
- Install the helper — asks for your password once (see why).
- Connect your agents — offers the agents it finds on this Mac (Claude Code, Codex CLI, Cursor…) and adds its hooks without touching yours. Anything it misses is in the Agent hooks submenu, see Agents.
That's it: a light appears in the menu bar and the cable starts showing what your agent is doing.
Updates: once a day the app asks GitHub for the latest release. When there is one, it offers to install it: it downloads the same zip, verifies the checksum and restarts itself. If the helper changed too, it asks for your password once. You can turn the check off in Updates, or update by running the install command again.
Requirements: a Mac with MagSafe 3 (MacBook Air M2 or later, MacBook Pro 14″/16″ 2021 or later), macOS 13+. On a Mac without the MagSafe LED the installer stops and tells you so.
Tested on a MacBook Pro M4 Pro with macOS 26. macOS 13–15 should work but haven't been tried yet. If you run one of them, an issue saying whether it works helps a lot.
PlugLight is free and is not signed with a paid Apple Developer ID. macOS quarantines apps downloaded by a browser and blocks unsigned ones; files fetched with curl are not quarantined, so the app just opens.
If you prefer to download PlugLight.zip manually: open the app, let macOS block it, then go to System Settings → Privacy & Security → Open Anyway. Or run:
xattr -dr com.apple.quarantine "/Applications/PlugLight.app"
git clone https://github.com/onelenyk/pluglight.git && cd pluglight
make install-app # needs Xcode Command Line Tools
curl -fsSL https://raw.githubusercontent.com/onelenyk/pluglight/main/get.sh | sh -s -- uninstall
Removes the hooks, the helper and the app, and hands the LED back to macOS.
The menu bar app
The menu bar icon mirrors the current state. From the menu you can:
- see the LED state and every active agent session;
- Enabled — switch off to give the LED back to macOS;
- Test LED — cycle through all states, 3 seconds each;
- Agent hooks — a submenu with every supported agent: the ones found on this Mac toggle on click, with a ✓ once connected, and the rest are listed greyed out as “not installed”;
- Helper — reinstall or remove;
- Updates — check now, or turn off the daily check;
- Launch at login, About, Quit.
The LED shows agent state only while the app is running and enabled. Quit it, and within a couple of seconds the cable is back to its normal charging indicator. The app follows your system language: English or Ukrainian.
How it works
flowchart LR
A["Agent hooks<br/>Claude Code, Codex, Cursor…"] -->|"pluglight hook busy"| B["/tmp/pluglight/<br/>one file per session"]
C["Menu bar app"] -->|"heartbeat every 1 s"| B
B --> D["Helper<br/>(root LaunchDaemon)"]
D -->|"SMC key ACLC"| E["MagSafe LED"]
The LED is driven by the Mac's System Management Controller through the undocumented ACLC key:
| Value | Effect |
|---|
0 | macOS controls the LED |
1 | off |
3 | green |
4 | orange |
Only root may write to the SMC, and an agent hook can't ask for a password every time. So the tool is one dependency-free C binary with two roles:
pluglight hook <state> [agent] — called by agent hooks, no root needed. Reads the session id from the event JSON on stdin and writes the state to a file. Prints nothing and always exits 0, so it never slows down or breaks the agent.pluglight daemon --require-app — the helper, running as root. Every half second it picks the most important state across sessions and drives the LED, including blinking. While the app's heartbeat is fresh, it re-asserts its color every 5 s, because macOS may override it (for example when charging state changes).
A state expires without updates — working after 20 min, waiting after 1 h, done and error after 10 min — so a crashed agent can't leave the light stuck.
Agents
# from a checkout
./install-hooks.sh codex
# from the installed app
"/Applications/PlugLight.app/Contents/Resources/install-hooks.sh" codex
# every agent whose config already exists on this Mac, and removing again
./install-hooks.sh all
./install-hooks.sh all remove
The installer adds PlugLight's hooks to that agent without touching yours; a second run replaces its own entries instead of duplicating them, and keeps the previous file as *.bak-pluglight-<time>.
| Agent | Where the hooks go | States wired |
|---|
| Claude Code | ~/.claude/settings.json | all five |
| Codex CLI | ~/.codex/hooks.json | working, waiting, done, idle |
| Qwen Code | ~/.qwen/settings.json | all five |
| Gemini CLI | ~/.gemini/settings.json | working, waiting, done, idle |
| Cursor | ~/.cursor/hooks.json | working, done, error, idle |
| Antigravity | ~/.gemini/config/hooks.json | working, done, error |
| Copilot CLI | ~/.copilot/hooks/pluglight.json | all five |
| OpenCode | ~/.config/opencode/plugins/pluglight.js (plugin) | all five |
Each mapping is written from the tool's own event list, and Claude Code is the one wired and verified end to end here. Codex, Gemini, Cursor, Antigravity and Copilot have not been tried against a signed-in account yet — if one of them misreports a state, an issue helps.
Cursor, Antigravity and Gemini end a turn with a stop event whose payload says why, so the hook reads the reason: completed turns the LED green, error blinks fast, aborted (Esc) clears the session, and Antigravity's "fullyIdle": false means background tasks are still running.
Claude Code events
| State | Events |
|---|
| working | UserPromptSubmit, PostToolUse, PostToolUseFailure, PermissionDenied, ElicitationResult, PreCompact |
| waiting | PermissionRequest, PreToolUse (AskUserQuestion), Elicitation, Notification (permission or question) |
| done | Stop |
| error | StopFailure |
| idle | SessionEnd |
Any other agent can be connected by hand: call pluglight hook <state> <agent> from its hook and pass the event on stdin. The session id is taken from session_id, sessionId, conversation_id, conversationId or trajectory_id, whichever the tool sends.
Command line
pluglight status # sessions and what the LED shows
pluglight set busy # set a state by hand (session "manual")
pluglight set idle # remove it
pluglight clear # remove all sessions
pluglight probe # does this Mac have the MagSafe LED?
sudo pluglight led 3 # write ACLC directly
sudo pluglight blink 3 # test: green, orange, off
States: busy, waiting, done, error, idle (removes the session), notification (same as waiting).
Prefer no menu bar app? ./install.sh installs the helper in always-on mode and ./install-hooks.sh claude adds the hooks.
Is it safe?
- It writes only one SMC key,
ACLC, and only values 0–7. That key is purely an indicator and has no effect on charging.
- Nothing persists across reboots. If anything looks off:
sudo pluglight led 0 or re-plug the cable.
- The key is undocumented by Apple. Values come from open-source projects and are verified on an M4 Pro; a future macOS update could change them.
- Any local process can write a state into
/tmp/pluglight and so change the LED color. Nothing else can be done through it.
See SECURITY.md for the details of the root helper.
Tests
| Test | What it checks | Where |
|---|
make test | state logic without touching the SMC: priority, expiry, idle, session names, per-agent session ids, the stop payload | every commit, GitHub Actions |
tests/hooks-install.sh | the hook installer: every agent, merging with foreign hooks, re-running, remove | every commit, GitHub Actions |
tests/plugin-opencode.sh | the OpenCode plugin under real Bun: events become states (skipped when Bun is absent) | every commit, GitHub Actions |
tests/e2e-claude.sh | real Claude Code in tmux: prompt → Bash permission → approve → end of turn → /exit | by hand, needs a Claude login |
tests/e2e-app.sh | real clicks through the menu bar app via System Events | by hand, needs Accessibility permission |
Latest tests/e2e-claude.sh run (Claude Code 2.1.302, MacBook Pro M4 Pro, macOS 26.3):
01:12:22 none
01:12:25 busy prompt sent
01:12:27 waiting Claude asks for Bash permission
01:12:30 busy approved, command runs
01:12:31 done end of turn
01:12:33 gone /exit, session removed
ok state sequence matches
Related
- AgentLight — the same idea as a standalone ESP32 desk lamp, with full color.
License
MIT © onelenyk
