Harbor Light
Download: GitHub Releases
A status light for coding agents. You can see whether Codex or Cursor is working, waiting for confirmation, or already finished, without switching back to that window.
Harbor Light turns live Codex and Cursor activity into a red, yellow, and green overlay you can drag across screens. It keeps a separate record for each app, project, and conversation, so several tasks can light up at once. The current version is 0.1.0. It supports macOS 12+ and Windows 10/11 (x64 and ARM64). The core is Rust, with no Python or Swift runtime. Source: harbor-light.
What it does
- Read the state at a glance: yellow while working, red while waiting, green when finished.
- Keep tasks separate: watch several Codex and Cursor projects and chats at the same time. One finished task does not hide another that is still running.
- Stay out of the way: the window stays on top, does not steal focus, and remembers where you dragged it.
- Ready after install: it merges user-level Codex and Cursor hooks and sets itself to start at login.
How to read the lights
| State | Meaning | Overlay |
|---|---|---|
| Yellow | The agent is thinking or running a task | Breathing |
| Green | The current task is finished | Pops in, then returns to idle after about 3 seconds |
| Red | Approval is needed, or an error needs attention | Fast blink |
| Red and yellow | One task is waiting while another is still running | Blink together |
| Idle | Nothing is active | All three lights stay dim |
Drag the black capsule to place it on another screen. The window remembers that position. If a display is unplugged and the window is left off-screen, it returns to the top-right of the main display. Open the menu from the macOS menu bar, or right-click the Windows tray icon, to see the current state, reinstall hooks, or quit. The macOS menu can also toggle launch at login.
How it works
Codex and Cursor hooks send events to a provider adapter, which writes activity files under ~/.harbor-light/activities/. Codex rollout JSONL is a fallback. The overlay reads those files and combines them into one light.
| What is happening | What you see |
|---|---|
| Waiting, while another chat is still working | Red and yellow blink together |
| Waiting only | Red blinks |
| No waiting, but something is still working | Yellow breathes |
| Nothing active, but a completion has not timed out | Green pops in |
| Everything is idle, or completion has timed out | All three lights stay dim |
A green completion stays out of the mix while anything is still waiting or working. The same Codex session can show up in a hook, an old status file, and a rollout log. Those records are deduped by provider and session, and hooks win, so a fallback rollout does not turn the yellow light on during an approval.
When one app quits, only that app's activities are cleared. An activity with no new events for 30 minutes returns to idle.
Download and install
Installers are on GitHub Releases.
| Platform | Notes |
|---|---|
| macOS 12+ | Double-click the .pkg. It installs into Applications and configures hooks and launch at login. If it is unsigned, Control-click the package and choose Open |
| Windows 10/11 x64 / ARM64 | Double-click the setup.exe for your architecture. It installs for the current user under %LOCALAPPDATA%\HarborLight and does not need an administrator. If SmartScreen blocks it, choose More info, then Run anyway |
A Windows portable zip needs one install step after you unpack it: HarborLight.exe install. That writes the hooks and the login startup entry.
To build from source you need Rust. On macOS, install the Xcode Command Line Tools and run make install in the repository. On Windows, install the MSVC Build Tools with Desktop development with C++, then run harbor-light.exe install after the release build.
Hooks
The installer merges user-level Codex and Cursor hooks and does not replace entries you already have. If you configure them by hand, the command must be an absolute path.
| App | What turns the light on |
|---|---|
| Codex | Starting a session, submitting a prompt, or using a tool is yellow. A permission request is red. Stop or session end is green |
| Cursor | Submitting a prompt is yellow. An explicit approval request, or an execution error, is red. A normal stop is green |
Cursor does not yet expose a separate approval event. Ordinary commands are not treated as "waiting", so a running install does not flash red by mistake. User-level hooks watch the local agent only. This version does not configure Cloud Agent hooks.
Uninstall
On macOS, run make uninstall in the repository. On Windows, remove it from Settings, or run:
& "$env:LOCALAPPDATA\HarborLight\HarborLight.exe" uninstall
Uninstall stops the app, removes launch at login, and deletes only the hook entries this tool wrote. Your other hooks stay in place.