logoctl

---
name: logoctl
description: Control the illuminated Apple logo on the MacBook lid with the `logoctl` CLI. Use it to get the user's attention when they may be away from the screen (a long task finished, input needed), to set up logo-based status lights with Claude Code hooks, or when the user asks to change, dim, animate or check the logo light.
---

# logoctl

`logoctl` drives the glowing Apple logo on the back of the lid. The person
can see it from across the room when the screen isn't in view, which makes it
a good signal for someone who has stepped away.

Check it's available first: `command -v logoctl`. If it's missing, or `logoctl
status` reports that no logo light was found, the Mac has no controllable logo.
Don't try to install it unless the user asks.

## Commands

| Command | Effect |
|---|---|
| `logoctl status --json` | Read state: `on`, `level`, `nits`, `limits`, `lux`, `displayNits` |
| `logoctl blink [--count N] [--level L] [--interval S]` | Blink, then restore the previous state |
| `logoctl breathe [--period S] [--min L] [--max L]` | Breathe until killed, then restore |
| `logoctl stream` | Read levels from stdin, one per line (`75%`, `750nits`, `on`, `off`); restores on EOF |
| `logoctl set L` / `max` / `on` / `off` | Persistent change (lasts until reboot) |
| `logoctl auto` | Follow screen brightness (Apple's default) |
| `logoctl limits on\|off` | Apple's room-light limits on the logo |
| `logoctl fade S` | Fade time for sleep, lid close and wake |
| `logoctl reset` | Restore every setting to Apple's defaults |

Levels are percent (`60`, `60%`) or nits (`600nits`, max 1000).

## When to use it

**Good uses:**
- **Getting attention.** Run `logoctl blink --count 2` when a long-running task
  finishes or you need input and the user may have stepped away.
- **Status lights,** when the user asks for them. See the hooks below.
- **Direct requests** to dim, brighten, turn off, animate or check the logo.

**Avoid:**
- Persistent changes the user didn't ask for (`set`, `off`, `limits`, `fade`).
  These change how their Mac looks until reboot. For notifications, use
  `blink`, which restores the previous state on its own.
- Blinking on every small event. Save it for things worth looking up for.
- Running `breathe` or `stream` in the foreground, because they block until
  killed. Run them in the background and stop them with
  `pkill -f "logoctl breathe"`. That sends SIGTERM, and logoctl restores the
  previous state on the way out.
- Running `reset` to "clean up". It discards any settings the user made. To
  undo your own changes, put back the values you read from
  `logoctl status --json` beforehand.

## Claude Code hooks

Add these to `~/.claude/settings.json` (all users) or `.claude/settings.json`
(one project), and merge them with any existing `hooks`. Show the user the
change and get their agreement before writing it.

**Blink when Claude needs the user:**

```json
{
  "hooks": {
    "Notification": [
      { "hooks": [{ "type": "command", "command": "logoctl blink --count 2" }] }
    ]
  }
}
```

**Breathe while Claude works, stop when it's done:**

```json
{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "pkill -f 'logoctl breathe'; nohup logoctl breathe --period 3 --min 20% >/dev/null 2>&1 &" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "pkill -f 'logoctl breathe'; true" }] }
    ],
    "Notification": [
      { "hooks": [{ "type": "command", "command": "pkill -f 'logoctl breathe'; sleep 0.3; logoctl blink --count 2" }] }
    ]
  }
}
```

Wait for the logo to settle (about 0.3 s) between stopping an animation and
starting the next one. Otherwise the second one saves the half-restored state
and puts that back when it exits.

## Behaviour to know

- Settings last until reboot or until `corebrightnessd` restarts.
- The daemon smooths brightness changes at about 2000 nits/s, so very fast
  effects blur. `blink` stays crisp because it toggles on/off, which is
  instant.
- The logo fades out on its own when the display sleeps or the lid closes.
- Only one animation should run at a time. Two `breathe` processes will fight.