Know when your coding agents need you—without leaving the notch.
Moonglade is a quiet, native macOS indicator for Claude Code, OpenCode, Codex CLI, Pi, and Convoy pipeline sessions. It lives around the MacBook notch (or as a pill on displays without one) and returns you to the exact terminal tab, Orca terminal, or tmux pane with one click.
Why Moonglade?
- See global counts for running, waiting, and blocked sessions without having to infer them from provider icons.
- Click the status summary and its wide session menu grows out of the notch itself: provider, status light, session title taken from the live terminal tab, project directory, git branch (worktrees included) or Convoy pipeline step, and elapsed time.
- Focus the recorded Ghostty, iTerm2, Terminal, or tmux session with one click.
- Focus the exact Orca terminal through its stable handle. Register the Orca CLI in Orca → Settings → General → Orca CLI first.
- Focus the exact Herdr pane through Herdr's public CLI, then raise its outer
terminal application when available; Claude Code, OpenCode, Codex, and Pi
remain the displayed agent types.
- Expand any row (chevron or right click) for inline actions: rename the session, copy the project path, reveal it in Finder, or kill the process — SIGTERM with SIGKILL escalation — and close its exact tmux pane or Ghostty tab.
- Watch Convoy pipeline runs as first-class sessions: the current step in the row, red light on human gates, and no duplicate rows for the OpenCode sessions a pipeline owns.
- Closed terminals disappear immediately through kernel exit notifications, with a five-second scanner/reaper backstop for missed hooks and stale state.
- Follow the screen with the pointer by default, or choose the screen with the focused window — or a panel on every connected display — in Settings.
- Read a panel that belongs on the hardware: it hangs from the notch as a liquid-glass drop, stays pure black across the camera band, and answers the click with a Metal ripple. Frost and tint are tunable per display kind, and optional sounds can announce a session that needs you or one that just finished its turn.
- Keep all observation and state on your Mac.
- Run without telemetry, accounts, servers, or third-party Swift dependencies, at ~1% CPU and ~16 MB of memory.
Session states
| State | In the bar | Meaning |
|---|
| Running | Braille dot-matrix spinner | The agent is processing. |
| Waiting | Green dot | The session waits at the prompt for your next input. |
| Blocked | Red dot | A question, permission ask, or failed pipeline step needs you. |
Running and waiting sit on the left of the camera and blocked on its right, and each pair puts its round glyph on the outer screen edge so both wings meet the notch shoulders symmetrically. The bar shows a count for each state that actually exists right now — zero-count states leave no slot behind — and collapses to a single dimmed moon when no agent is running at all.
The menu always shows the real status and provider per session, using the same three glyphs plus a grey dot for a session whose process has exited and is about to be reaped.
Requirements
- macOS 14 Sonoma or newer — macOS 26 for the real Liquid Glass backdrop, which degrades to a system blur below it;
- a MacBook with a notch for the intended UI placement;
- Swift 6.0 or newer to build from source;
- Node.js 20+ to run the OpenCode and Pi behavioral tests;
- OpenCode 2 for the OpenCode integration — its plugin uses the V2 plugin API, which OpenCode 1 cannot load;
- Ghostty 1.3+ with AppleScript enabled, cmux with AppleScript enabled, iTerm2, or Terminal.
- Orca Terminal with its CLI registered in Orca → Settings → General → Orca CLI for exact Orca focus.
Apple Silicon is the tested development platform. Intel builds have not yet been validated.
Install
One command downloads the latest release, verifies it against the published checksums, installs it into /Applications, wires the agent hooks, launches it, and verifies everything:
curl -fsSL https://moonglade.josemi.me/install | sh
Read the script before running it if you would rather see what it does first. It needs Apple Silicon and macOS 14+, and it never prompts. Because curl does not set the quarantine attribute a browser download would, the app is not sent through Gatekeeper's unidentified-developer wall and you are never asked to disable a security control — the build is signed, but with a self-signed certificate rather than an Apple Developer identity, so it is not notarized.
To build it yourself instead — the path for Intel Macs, which the published build does not cover — clone and run the source installer, which needs Swift 6.0 or newer:
git clone https://github.com/ixjosemi/Moonglade.git
cd Moonglade
./scripts/install.sh
Either command reinstalls: it stops the running instance, replaces the app, relaunches, and re-verifies. A local source build is ad-hoc signed — do not redistribute it as an official release.
Verify an existing installation at any time:
/Applications/Moonglade.app/Contents/Resources/bin/moonglade doctor
✓ hook binaries: all executables present in ~/.moonglade/bin
✓ state directory: ~/.moonglade/state exists
✓ Claude Code hooks: all lifecycle hooks registered in ~/.claude/settings.json
✓ OpenCode plugin: ~/.config/opencode/plugins/moonglade.js matches the bundled file
✓ Codex notify: notify hook registered in ~/.codex/config.toml
✓ Pi extension: ~/.pi/agent/extensions/moonglade.ts matches the bundled file
doctor is read-only and exits non-zero when something is broken, so it is also usable from scripts.
Manual build
For development without touching /Applications:
swift build
swift run moonglade-tests
./scripts/build-app.sh
open .build/Moonglade.app
This is the beginning of the README. Read the rest at the original. Read the full README ↗
