Metadata-Version: 2.5
Name: agenthud
Version: 0.1.5
Summary: Cross-tool agent session HUD for Cursor, OpenCode, Freebuff, Codex, and more
Project-URL: Homepage, https://github.com/scs0209/agenthud
Project-URL: Repository, https://github.com/scs0209/agenthud
Project-URL: Issues, https://github.com/scs0209/agenthud/issues
Project-URL: Release, https://github.com/scs0209/agenthud/releases
Author-email: ayaan <scs0209@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: agents,claude,cli,codex,cursor,freebuff,hud,menubar,opencode
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: pyobjc-framework-cocoa>=10; sys_platform == 'darwin'
Requires-Dist: pyobjc-framework-webkit>=10; sys_platform == 'darwin'
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# 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?*

<p align="center">
  <img src="docs/media/demo.gif" alt="agenthud demo — popover tabs and settings" width="420" />
</p>

<p align="center">
  <img src="docs/media/popover.png" alt="agenthud menu bar popover" width="320" />
  &nbsp;
  <img src="docs/media/settings.png" alt="agenthud settings" width="280" />
</p>

> 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)

```bash
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`):

```bash
brew trust scs0209/agenthud
brew install scs0209/agenthud/agenthud
```

### pip

```bash
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

```bash
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

```bash
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](CONTRIBUTING.md). Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).

## 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](LICENSE)
