agenthud

Cross-tool agent session HUD for macOS.

See every coding agent at a glance — Cursor, OpenCode, Freebuff, Codex, Claude Code, and more — without alt-tabbing through ten windows.

agenthud reads local session data only (no cloud login, no usage quotas). It answers: who is waiting on me, who is running, who errored?

 

Not affiliated with Cursor, OpenAI, Anthropic, or any agent vendor.

Why

Running multiple agents in parallel is normal now. Finding the one that needs approval is not. agenthud puts a small menu-bar badge and a popover over your local sessions so you can jump straight to the right tool.

Features

• Menu bar HUD — status badge (● waiting / ✖ error / ▶ running) + popover
• Per-agent tabs — only the agent you select
• Auto-detect — on first launch, enables tools that look installed on this Mac
• Settings — enable/disable agents; Install for missing ones (Terminal or download page)
• Click to focus — open the matching app / project when possible
• TUI + JSON — agenthud, agenthud --once, agenthud --json
• Privacy-first — read-only local files; never prints tokens

Requirements

• Python 3.11+
• macOS for the menu bar UI (PyObjC + WebKit)
• Linux/macOS terminal TUI works with rich only

Install

Homebrew (macOS app — recommended)

brew trust scs0209/agenthud
brew install --cask scs0209/agenthud/agenthud

Then open AgentHUD, or run agenthud menubar.

Upgrade: brew upgrade --cask agenthud

CLI-only (no .app):

brew trust scs0209/agenthud
brew install scs0209/agenthud/agenthud

pip

pip install https://github.com/scs0209/agenthud/releases/download/v0.1.5/agenthud-0.1.5-py3-none-any.whl

PyPI (pip install agenthud) is wired via GitHub Actions trusted publishing — publish completes once a PyPI project + trusted publisher (or PYPI_API_TOKEN secret) is connected.

From source

git clone https://github.com/scs0209/agenthud.git
cd agenthud
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

First launch may show a Gatekeeper prompt (ad-hoc signed). Prefer right-click → Open, or: xattr -dr com.apple.quarantine /Applications/AgentHUD.app

macOS 26 (Tahoe): if the app launches but you see nothing, open System Settings → Menu Bar and enable AgentHUD under “Allow in the Menu Bar” (not leftover python3.13 entries from older builds). agenthud will also show a guidance dialog when it detects a hidden icon.

Usage

agenthud menubar          # macOS menu bar (recommended)
agenthud                  # terminal live TUI
agenthud --once           # one snapshot
agenthud --json           # machine-readable
agenthud --tools cursor,codex
agenthud --max-age-hours 24

Prefs: ~/.config/agenthud/settings.json

Environment overrides

Variable	Default
AGENTHUD_CURSOR_PROJECTS	~/.cursor/projects
AGENTHUD_OPENCODE_DB	~/.local/share/opencode/opencode.db
AGENTHUD_FREEBUFF_DIR	~/.config/freebuff-desktop

Status legend

Status	Meaning
waiting	Needs you
running	Recent activity / turn in flight
error	Last turn failed
idle	Quiet
done	Finished / stale

Statuses are best-effort heuristics from local logs/DBs. Agents without a live status API are inferred from mtime and last message role.

Supported agents

Agent	Session parsing	Detect / install
Cursor	✅	✅
OpenCode	✅	✅
Freebuff	✅	✅
Codex	✅	✅
Claude Code	✅	✅
Gemini CLI, Copilot CLI, Amp, Factory, Pi, Kiro, Cline, Roo	listed in Settings	detect + install recipes; parsers welcome

Architecture (short)

src/agenthud/
  adapters/     # per-tool collectors (read-only)
  registry.py   # agent catalog + install detection
  install.py    # install recipes (Terminal / URL)
  native_menubar.py  # macOS status item + WKWebView popover
  assets/       # popover.html, settings.html
  tui.py / cli.py

Contributing

See CONTRIBUTING.md. Please follow the Code of Conduct.

Security & privacy

• Read-only access to local agent stores
• Freebuff state.json tokens are never printed
• No telemetry, no accounts, no network required for core HUD

If you find a vulnerability, open a private security advisory or email the maintainer — do not file a public issue with exploit details.

License

MIT