{"slug": "mux-beacon-macos-menu-bar-inbox-for-claude-code-codex-agents-in-tmux", "title": "Mux Beacon – macOS menu-bar inbox for Claude Code/Codex agents in tmux", "summary": "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.", "body_md": "Know when terminal agents need you—and get back to the exact tmux target.\n\nMux 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.\n\nA busy tmux setup can hide finished work across sessions and windows. Mux Beacon turns each agent turn into a small lifecycle:\n\n```\nprompt submitted → working → ready / failed\n                         └→ needs attention (optional)\n```\n\n`UserPromptSubmit`\n\nrecords the start immediately; its notification is opt-in to avoid noise.- Completion and failure notifications contain agent, project, duration, and\n`session › window`\n\n. - Clicking\n**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`\n\nis supported but its notification is off by default.- Prompts, commands, and final answers are not stored unless previews are explicitly enabled.\n\n- macOS 13 or newer\n- tmux 3.2 or newer\n- A recent Claude Code with lifecycle hooks (including\n`StopFailure`\n\n), 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\n\n```\ngit clone https://github.com/Lukeesec/mux-beacon.git\ncd mux-beacon\n./scripts/install-local.sh\nmux-beacon install          # dry run: preview the hook changes\nmux-beacon install --apply  # write them\n```\n\nThe app installs into `/Applications`\n\nwhen writable, otherwise `~/Applications`\n\n, and registers with Launch Services. Finder can open it directly; `mux-beacon gui`\n\nis the reliable launcher for local ad-hoc builds that Spotlight has not indexed yet.\n\nApplying the installation:\n\n- adds owned handlers to\n`~/.claude/settings.json`\n\n; - adds owned handlers to\n`~/.codex/hooks.json`\n\n; - adds Codex's documented\n`agent-turn-complete`\n\ncallback to`~/.codex/config.toml`\n\nwhen the`notify`\n\nslot is free; - preserves an existing Codex\n`notify`\n\ncommand and prints a warning instead of replacing it; - writes timestamped backups before changing existing files.\n\nCodex asks you to review new hooks once. Open `/hooks`\n\nand trust the Mux Beacon definitions. The completion callback covers Codex versions where the lifecycle `Stop`\n\nhook is not emitted after each turn.\n\nPermission events are deferred by default. Users who want them can install the adapter explicitly and then enable its notification in Settings:\n\n```\nmux-beacon install --apply --with-permission-events\n```\n\nAllow 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**.\n\nMux 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:\n\n```\nmux-beacon gui\n```\n\nLaunching 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`\n\nrequest, or `muxbeacon://inbox`\n\nbrings it forward. Notification navigation returns directly to Ghostty and the captured tmux target.\n\n```\nmux-beacon demo\nmux-beacon test ready --source codex\nmux-beacon status\n```\n\nThe app and demo require no tmux restart. Hooks may require a new or reloaded agent process.\n\nMux 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.\n\nmacOS 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.\n\nDemo records are marked `DEMO`\n\nand intentionally have no live jump target. The GUI keeps sample-data controls out of the normal workflow; remove samples with `mux-beacon clear-demo`\n\n.\n\nCompletion and failure alerts are on. Start and permission alerts are off. Change them in the GUI or from the CLI:\n\n```\nmux-beacon notifications status\nmux-beacon notifications start on\nmux-beacon notifications start off\nmux-beacon notifications all off\n```\n\nChoose the level you want:\n\n```\n# Silence every notification but keep recording turns in the inbox\nmux-beacon notifications all off\n\n# Stop collecting new events by removing only Mux Beacon's agent hooks\nmux-beacon uninstall --apply\n\n# Remove hooks and move the app to Trash; local history is retained\n./scripts/uninstall-local.sh\n```\n\nThe state appears at the left of each pane's top border—blue `● WORKING`\n\n, green `● READY`\n\n, yellow `● ATTENTION`\n\n, or red `● FAILED`\n\n—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.\n\n```\nmux-beacon tmux popup\nmux-beacon tmux enable-badges\nmux-beacon tmux disable-badges\nmux-beacon tmux badge-status\n```\n\n`mux-beacon tmux popup`\n\nopens a temporary tmux overlay of recent agent activity. Enter a row number to jump to that agent; press Return to close it.\n\nBadges are opt-in and apply to the current tmux server. Run `enable-badges`\n\nonce from inside that server; `badge-status`\n\nreports whether borders are enabled and how many panes have tracked state. Mux Beacon saves the exact existing `pane-border-status`\n\nand `pane-border-format`\n\nand restores them with `disable-badges`\n\n.\n\nTurn duration is measured from prompt submission until completion or failure.\n\n```\nmux-beacon export --format json --output mux-beacon-time.json\nmux-beacon export --format csv --output mux-beacon-time.csv\n```\n\nThe core exposes `TimeExportProvider`\n\nand `TimeEntryDraft`\n\nso 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).\n\n| Command | Purpose |\n|---|---|\n`mux-beacon doctor` |\nCheck app, hooks, tmux, Ghostty, and local storage |\n`mux-beacon status` |\nShow recent activity in the terminal |\n`mux-beacon health` |\nRetire superseded records and missing tmux targets |\n`mux-beacon gui` |\nOpen the native inbox window |\n`mux-beacon notifications …` |\nInspect or change alert preferences |\n`mux-beacon jump-last` |\nOpen the newest unread event |\n`mux-beacon demo` / `clear-demo` |\nAdd or remove anonymized sample data |\n`mux-beacon uninstall --apply` |\nRemove only Mux Beacon's hook handlers |\n\nMux Beacon stores stable tmux IDs and the exact server socket. Navigation uses:\n\n```\ntmux -S <socket> switch-client -c <client-tty> -t <pane-id>\n```\n\nGhostty 1.3 does not expose a terminal TTY, so Mux Beacon captures the focused terminal ID synchronously at prompt submission. Ghostty 1.4 adds TTY/PID properties, allowing direct mapping. Ambiguous or stale routes fail closed instead of switching an arbitrary terminal.\n\nThe inbox checks target health every 30 seconds and whenever **Refresh** is clicked. Older active turns on the same tmux target and events whose panes no longer exist are acknowledged as stale and retained under **History** for 7 days. Running and unread records are never removed by history cleanup.\n\nSee [Architecture](/Lukeesec/mux-beacon/blob/main/docs/ARCHITECTURE.md), [Development](/Lukeesec/mux-beacon/blob/main/docs/DEVELOPMENT.md), and [Troubleshooting](/Lukeesec/mux-beacon/blob/main/docs/TROUBLESHOOTING.md).\n\nTagged releases attach an app zip built by CI. It is ad-hoc signed and not notarized, so macOS blocks the first launch of a downloaded copy: approve it under **System Settings → Privacy & Security → Open Anyway**, or build from source as shown above (local builds are not quarantined).\n\n- Local-only SQLite database; no telemetry.\n- User-only application-support directory and hook backups.\n- No approval or denial actions from notifications.\n- Opaque event IDs in notification metadata; no shell commands or tmux labels in URLs.\n- Hook commands return success without steering the agent.\n\n- Developer ID signing and notarization for release builds, so downloads pass Gatekeeper without manual approval.\n- Clockify export adapter on the existing provider boundary (\n[design](/Lukeesec/mux-beacon/blob/main/docs/CLOCKIFY.md)).\n\nMIT © 2026 Lukeesec contributors.", "url": "https://wpnews.pro/news/mux-beacon-macos-menu-bar-inbox-for-claude-code-codex-agents-in-tmux", "canonical_source": "https://github.com/Lukeesec/mux-beacon", "published_at": "2026-08-13 00:32:51+00:00", "updated_at": "2026-08-13 00:40:54.919343+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Mux Beacon", "Claude Code", "Codex", "Ghostty", "tmux", "GitHub", "Lukeesec"], "alternates": {"html": "https://wpnews.pro/news/mux-beacon-macos-menu-bar-inbox-for-claude-code-codex-agents-in-tmux", "markdown": "https://wpnews.pro/news/mux-beacon-macos-menu-bar-inbox-for-claude-code-codex-agents-in-tmux.md", "text": "https://wpnews.pro/news/mux-beacon-macos-menu-bar-inbox-for-claude-code-codex-agents-in-tmux.txt", "jsonld": "https://wpnews.pro/news/mux-beacon-macos-menu-bar-inbox-for-claude-code-codex-agents-in-tmux.jsonld"}}