Mux Beacon – macOS menu-bar inbox for Claude Code/Codex agents in tmux Mux Beacon, a native macOS menu-bar inbox for Claude Code and Codex terminal agents, tracks agent turns via lifecycle hooks and completion callbacks, recording local turn duration and enabling actionable notifications that return users to the exact tmux target in Ghostty. The tool, available on GitHub, requires macOS 13+, tmux 3.2+, and a recent Claude Code or Codex CLI with hooks, and installs via a script that modifies configuration files with backups. Know when terminal agents need you—and get back to the exact tmux target. Mux Beacon is a native macOS menu-bar inbox for Claude Code and Codex. It uses documented lifecycle hooks and completion callbacks, records local turn duration, shows optional pane-border badges, and makes notifications actionable. A busy tmux setup can hide finished work across sessions and windows. Mux Beacon turns each agent turn into a small lifecycle: prompt submitted → working → ready / failed └→ needs attention optional UserPromptSubmit records the start immediately; its notification is opt-in to avoid noise.- Completion and failure notifications contain agent, project, duration, and session › window . - Clicking Open in Ghostty targets the originating tmux client and focuses the captured Ghostty terminal. Acknowledge clears the unread state; Mark time logged is available in the inbox. PermissionRequest is supported but its notification is off by default.- Prompts, commands, and final answers are not stored unless previews are explicitly enabled. - macOS 13 or newer - tmux 3.2 or newer - A recent Claude Code with lifecycle hooks including StopFailure , or Codex CLI with hooks and its completion callback - Ghostty 1.3+ for exact window/tab focus; other terminals still receive the inbox and tmux metadata git clone https://github.com/Lukeesec/mux-beacon.git cd mux-beacon ./scripts/install-local.sh mux-beacon install dry run: preview the hook changes mux-beacon install --apply write them The app installs into /Applications when writable, otherwise ~/Applications , and registers with Launch Services. Finder can open it directly; mux-beacon gui is the reliable launcher for local ad-hoc builds that Spotlight has not indexed yet. Applying the installation: - adds owned handlers to ~/.claude/settings.json ; - adds owned handlers to ~/.codex/hooks.json ; - adds Codex's documented agent-turn-complete callback to ~/.codex/config.toml when the notify slot is free; - preserves an existing Codex notify command and prints a warning instead of replacing it; - writes timestamped backups before changing existing files. Codex asks you to review new hooks once. Open /hooks and trust the Mux Beacon definitions. The completion callback covers Codex versions where the lifecycle Stop hook is not emitted after each turn. Permission events are deferred by default. Users who want them can install the adapter explicitly and then enable its notification in Settings: mux-beacon install --apply --with-permission-events Allow notifications when macOS prompts. In System Settings → Notifications → Mux Beacon , choose Alerts instead of Banners if notifications should remain until dismissed; macOS owns this setting, so apps cannot enforce it. To enable exact Ghostty focus, allow Mux Beacon to automate Ghostty under System Settings → Privacy & Security → Automation . Mux Beacon is primarily a menu-bar app. Click its beacon icon in the macOS menu bar, open it from Finder or Spotlight when indexed, or run: mux-beacon gui Launching the app directly starts its menu-bar item without opening a window. Hook events and notification clicks never open or focus the inbox; only Open window , a fresh mux-beacon gui request, or muxbeacon://inbox brings it forward. Notification navigation returns directly to Ghostty and the captured tmux target. mux-beacon demo mux-beacon test ready --source codex mux-beacon status The app and demo require no tmux restart. Hooks may require a new or reloaded agent process. Mux Beacon is hook-driven rather than a process scanner. It begins tracking an agent when a hook-enabled prompt is submitted; it cannot reconstruct turns that were already running before installation. Merely launching Claude or Codex does not produce a start event. macOS renders the project and state as the bold title, with agent and duration beneath it and the tmux route in the body. It controls final layout, truncation, persistence, and Focus/DND delivery. Routing details live in hidden notification metadata as an opaque event ID. Demo records are marked DEMO and intentionally have no live jump target. The GUI keeps sample-data controls out of the normal workflow; remove samples with mux-beacon clear-demo . Completion and failure alerts are on. Start and permission alerts are off. Change them in the GUI or from the CLI: mux-beacon notifications status mux-beacon notifications start on mux-beacon notifications start off mux-beacon notifications all off Choose the level you want: Silence every notification but keep recording turns in the inbox mux-beacon notifications all off Stop collecting new events by removing only Mux Beacon's agent hooks mux-beacon uninstall --apply Remove hooks and move the app to Trash; local history is retained ./scripts/uninstall-local.sh The state appears at the left of each pane's top border—blue ● WORKING , green ● READY , yellow ● ATTENTION , or red ● FAILED —followed by the existing pane title and pane number. The illustration uses a neutral theme; tmux renders it using your terminal's font and background. These badges are most useful when a window is split into panes; desktop notifications and the menu-bar inbox provide visibility across hidden windows and sessions. mux-beacon tmux popup mux-beacon tmux enable-badges mux-beacon tmux disable-badges mux-beacon tmux badge-status mux-beacon tmux popup opens a temporary tmux overlay of recent agent activity. Enter a row number to jump to that agent; press Return to close it. Badges are opt-in and apply to the current tmux server. Run enable-badges once from inside that server; badge-status reports whether borders are enabled and how many panes have tracked state. Mux Beacon saves the exact existing pane-border-status and pane-border-format and restores them with disable-badges . Turn duration is measured from prompt submission until completion or failure. mux-beacon export --format json --output mux-beacon-time.json mux-beacon export --format csv --output mux-beacon-time.csv The core exposes TimeExportProvider and TimeEntryDraft so a Clockify adapter can be added without changing hook or UI code. Direct Clockify credentials and API calls are deferred from the first release; see Clockify integration design /Lukeesec/mux-beacon/blob/main/docs/CLOCKIFY.md . | Command | Purpose | |---|---| mux-beacon doctor | Check app, hooks, tmux, Ghostty, and local storage | mux-beacon status | Show recent activity in the terminal | mux-beacon health | Retire superseded records and missing tmux targets | mux-beacon gui | Open the native inbox window | mux-beacon notifications … | Inspect or change alert preferences | mux-beacon jump-last | Open the newest unread event | mux-beacon demo / clear-demo | Add or remove anonymized sample data | mux-beacon uninstall --apply | Remove only Mux Beacon's hook handlers | Mux Beacon stores stable tmux IDs and the exact server socket. Navigation uses: tmux -S