Red while an agent works.
Amber when one needs you.
Green when they're all free.
One browser toolbar lamp for every coding agent on your machine: Claude Code, Codex CLI, GitHub Copilot CLI and Antigravity CLI, plus opencode, Goose and Qwen Code on the free tier. Optional desktop notifications. It works on macOS, Ubuntu and Windows.
perturbation (n.): in physics and astronomy, a small disturbance of a system by an outside influence, stated without any judgement of whether the disturbance is welcome.
One lamp, four states
Only one lamp is ever lit, and the fill pattern carries the meaning without colour: solid, dotted, ring, dashed.
Perturbed
At least one agent is working. The badge counts the busy sessions.
Needs you
Nothing is working, but a session waits for a permission or an answer.
Unperturbed
Every watched agent is free.
Not connected
The local helper isn't running, or no agent is watched. Run the installer.
What you get
Small, local, and with no dependencies beyond Python 3.
- One button for every agentThe four earlier projects (Claudication, Codexalgia, Copilonidal, Antigravalgia) become one host, one extension, one lamp. The installer removes the old ones for you.
- A count, not a colourThe badge shows how many sessions are busy across every agent, so the lamp answers "how much" and not only "whether".
- Needs you, separatelyAmber is its own state, so an agent blocked on a permission never hides behind one that is still working.
- A popup you can shapeOne row per agent, a mute switch each, and drag rows into the order you want.
- Three platformsmacOS, Ubuntu/Linux and Windows. The installer detects which one you're on and which agents you have.
- Every Chromium browserChrome, Edge, Brave, Opera, Vivaldi, Arc or Chromium: tick the ones you use, get a lamp in each, and still one notification per event. No Chrome required.
- Stays out of the wayHooks that always exit 0 and print nothing, merged into files that stay yours and are backed up first.
- Fully localNothing leaves your machine. The status goes from each agent's hooks to the browser over native messaging.
Install
Requires Python 3.9 or newer and a Chromium browser: Chrome, Edge, Brave, Opera, Vivaldi, Arc or Chromium.
git clone https://github.com/Tpojka/perturbation.git
cd perturbation
./install.shsudo apt install python3 libnotify-bin # notify-send, for the notifier
git clone https://github.com/Tpojka/perturbation.git
cd perturbation
./install.shwinget install Python.Python.3.12 # if Python isn't installed
git clone https://github.com/Tpojka/perturbation.git
cd perturbation
install.cmdChoose what to watch and what to install
Which agents should be watched?
[x] 1) Claude Code found ~/.claude
[x] 2) Codex CLI found ~/.codex
[ ] 3) GitHub Copilot CLI not found
[x] 4) Antigravity CLI found ~/.gemini/antigravity-cli
[x] 5) opencode found ~/.config/opencode
[ ] 6) Goose not found
[ ] 7) Qwen Code not found
Space or 1-7 toggles, ↑/↓ moves, a: all, n: none, Enter confirms:
Which browsers should the lamp work in?
[x] 1) Google Chrome /Applications/Google Chrome.app
[ ] 2) Microsoft Edge not found
[x] 3) Brave /Applications/Brave Browser.app
[ ] 4) Opera not found
[ ] 5) Vivaldi not found
[ ] 6) Arc not found
[ ] 7) Chromium not found
Space or 1-7 toggles, ↑/↓ moves, a: all, n: none, Enter confirms:
What should be installed?
1) Browser extension
2) Browser extension + OS notifier
3) Nothing (exit)
Choose 1, 2 or 3: 2
Play a sound with notifications? [Y/n]:
Let Antigravity show "needs you" alerts? This sets its status line command. [y/N]:
Finish in your browser (once per browser)
- Open its extensions page (
chrome://extensions,edge://extensions,brave://extensions, …) and turn on Developer mode. - Click Load unpacked and pick the
extensionfolder itself, the path the installer printed — not the folder above it. - Pin Perturbation to the toolbar.
- Restart any running agent sessions so they load the hooks. In Codex, run
/hooksand trust the new hooks.
The same folder goes into every browser you ticked, and each one gets its own lamp showing the same thing — with a single notification, because that comes from the agent's hook and not from the browser. No Chrome needed: tick Brave alone and Brave alone is registered.
Browsers
The installer registers the native host once per browser you tick, and takes the registration away from one you untick. Where each browser looks for it:
| OS | Where the browser reads the host manifest |
|---|---|
| macOS | ~/Library/Application Support/<browser>/NativeMessagingHosts/com.tpojka.perturbation.json |
| Ubuntu/Linux | ~/.config/<browser>/NativeMessagingHosts/com.tpojka.perturbation.json |
| Windows | one manifest in the data directory, with HKCU\Software\<vendor>\NativeMessagingHosts\com.tpojka.perturbation pointing at it |
Some browsers also read Chrome's folder — on macOS, Brave and Opera both do. Perturbation still writes one manifest per browser, because that behaviour is undocumented, differs per platform, and points at a folder belonging to a browser you may not have. Arc is macOS-only, and Snap or Flatpak browsers on Linux cannot start a native host at all. Firefox is not supported: it speaks a different dialect and, unlike Chrome, refuses to keep an unsigned extension.
If the lamp stays grey
The popup prints the browser's own error. What each one means:
| Message | Cause |
|---|---|
| Specified native messaging host not found | That browser has no registration. Run set browsers and include it. |
| Access to the specified native messaging host is forbidden | The manifest is there but doesn't list this extension's ID. Run the installer again. |
| Manifest file is missing or unreadable | Load unpacked was pointed at the data directory instead of the extension folder inside it. |
| Not connected, with no message | The host started and died. python3 -m perturbation.install doctor says which part is missing. |
Had Claudication, Codexalgia, Copilonidal or Antigravalgia installed? The installer lists what they left behind and offers to remove it, keeps your notification settings, and prints the old extension IDs to remove on your browser's extensions page.
OS notifier
You get a notification when an agent finishes a turn and when it needs you. The title names the agent and the project.
| When | Title | Text |
|---|---|---|
| An agent finishes a turn | Claude is ready · project | the first line of its last message, or "Task finished" |
| An agent needs a permission or an answer | Codex needs you · project | the prompt, or what it wants to run |
| A turn ends with an error | Claude stopped · project | the error type |
Notifications are sent only when a session's state actually changes, never for a reminder that repeats a finished turn, and each agent can be muted in the popup.
Change settings any time
Run these from the repository. They take effect at once, with no restart:
python3 -m perturbation.install set agents claude,codex # watch exactly these
python3 -m perturbation.install set browsers chrome,brave # register these browsers
python3 -m perturbation.install set sound off
python3 -m perturbation.install set notifications off
python3 -m perturbation.install mute codex on # silence one agent, keep its lamp
python3 -m perturbation.install statusline antigravity on # "needs you" alerts for Antigravity
python3 -m perturbation.install status
python3 -m perturbation.install doctorOn Windows, use py -3 instead of python3.
How it works
Each agent's hooks write its sessions' state. One small local helper sends the sum to your browser.
Claude Code ──hook──┐
Codex CLI ──hook──┤
Copilot CLI ──hook──┼──► perturbation.pyz hook <agent> ──► sessions/<agent>/<session> (busy | waiting | ready)
Antigravity ──hook──┘ └──► desktop notification (optional)
browser ──starts──► perturbation.pyz host
watches sessions/, pushes a per-agent summary on change
│ native messaging
▼
extension: lamp + badge + tooltip, popup on clickEach agent is one small adapter that knows its hook file and its events. Everything else is shared: one hook handler, one state tree, one host, one lamp.
| Agent | Busy | Needs you | Ready |
|---|---|---|---|
| Claude Code | prompts, tool calls, compaction | permission prompts, questions | Stop, a manual compaction, an error |
| Codex CLI | prompts, tool calls | permission requests unanswered for 5 s | Stop, Interrupt |
| GitHub Copilot CLI | prompts, tool calls | permission prompts, questions | Stop, an unrecoverable error |
| Antigravity CLI | invocations, tool calls | its status line, when you turn it on | Stop when fully idle |
| opencode | session status, tool calls | permission prompts | session.idle, an error |
| Goose | prompts, tool calls, file and shell steps | never: Goose has no permission event | Stop |
| Qwen Code | prompts, tool calls, compaction | permission prompts and requests | Stop, a manual compaction, an error |
Every hook command exits 0 and prints nothing, even when Python or the app is missing. Copilot denies a tool call when a hook fails, Claude's PreCompact blocks compaction on exit 2, and Antigravity reads a hook's stdout as a decision, so this is what keeps the agents unharmed. A busy session with no activity for 15 minutes counts as ready, and one waiting for an hour does too, for the agents that never say goodbye.