convez.ai
Agente
alexey-krylov

ClaudeAgentsBar

alexey-krylov/ClaudeAgentsBar

Ver no GitHub
InicialPluginScore · de 0 a 100

See every Claude Code agent at a glance — macOS menu-bar status widget

Instalação

$npx convez-ai alexey-krylov/ClaudeAgentsBar

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v1.6.4
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

ClaudeAgentsBar

See which Claude Code session needs you, without ⌘-tabbing through windows. A SwiftBar plugin for macOS.

   ◐ 🟡1 🟢2 🔵1        ← menu bar: icon + colour counters
   ┌───────────────────────────────────────────────────────────┐
   │ 🟡 Refactor authentication middleware · working           │
   ├───────────────────────────────────────────────────────────┤
   │ 🟢 Add unit tests for the parser · 7m ago                 │
   │ 🟢 Investigate failing CI run · 18m ago                   │
   ├───────────────────────────────────────────────────────────┤
   │ 🔵 Wire up the new settings page · 32m ago                │
   ├───────────────────────────────────────────────────────────┤
   │ ⚪ Migrate config to TOML · 2h 14m ago                    │
   │ …                                                          │
   └───────────────────────────────────────────────────────────┘

Why I built this

I run a handful of Claude Code sessions in parallel — background agents, worktrees, the occasional long-running investigation — and kept losing track of which one had just finished, which one was sitting on a permission prompt, and which one I'd already triaged. The Claude Code sidebar (same in VSCode, VSCodium, and Cursor — they share the anthropic.claude-code extension) only sees the active workspace; ⌘-tabbing through windows to find the yellow dot got old fast, and I didn't want another floating panel stealing screen real estate. A menu-bar widget was the smallest thing that could answer "which agent needs me right now?" without pulling focus, so I wrote one for myself and then cleaned it up enough to share.

What it shows

Menu-bar counters — at a glance, no text labels:

GlyphMeaning
🟡 NN sessions are working or waiting on a permission prompt
🟢 MM sessions finished, you haven't seen them yet
🔵 KK sessions you've opened, still in active follow-up
(dim)nothing urgent — the title fades so it doesn't shout

Session states — each row in the dropdown carries one of four colours:

GlyphStateMeaning
🟡working / waitingClaude is running a tool, or paused on a permission prompt
🟢freshSession finished, you haven't opened it yet
🔵acknowledgedYou've opened it; still within the follow-up window
⚪staleNo interaction for a while — fades to grey, still reachable

Dropdown — every session active in the last 3 hours, sorted by urgency (active → fresh → acknowledged → stale). Click a row to open it in your editor (VSCode by default; VSCodium and Cursor via a one-line editor_url_scheme change). Above 80 % context usage the row gets an inline ⚠ {pct}% warning (red past 90 %), so a glance tells you which sessions are close to auto-compact.

Session titles — by default the row shows Claude's auto-generated ai-title, the same label VSCode displays, so the menu stays consistent with the editor. Set use_session_titles_for_menubar: true to instead use the name from Claude's response marker (*-- Session name - Summary*) — your own wording in place of the English auto-title. Either way that marker drives the spoken notifications (its primary purpose) — see docs/configuration.md § Spoken summary. Claude agents are instructed to end each reply with this line; you set that up once in your CLAUDE.md.

Submenu per row — Mark as read, Forget, Delete…, Reveal in Finder, plus git branch, the model running the session (claude-opus-4-7 / claude-sonnet-4-6 / …) and context %. Hovering the context line shows the session's last tool_use as a tooltip (e.g. Read: main.py, Bash: pytest …) — quick answer to what is this session doing? without expanding anything.

Subagent rollup — sessions that spawn Task subagents grow a 🤖×N badge with the live count, and the submenu lists each subagent (description, model chip, current tool, runtime). The parent row stays 🟡 while any subagent is in flight, so a long Task doesn't drift the parent into a misleading 🟢.

Tools submenu — bulk actions (acknowledge all / forget all), today's activity summary (sessions, turns, tokens, breakdown by model and subagent), a Notifications block with one-click pause / resume / bypass for quiet hours, Keep awake (off / auto / always — wraps caffeinate -i), a feedback link, and one-click jump to your config.json.

Audible nudges — when a session finishes (Stop) or stalls on a permission prompt (PermissionRequest), the plugin plays a short chime, speaks a random phrase via macOS say (default sets: "Done" / "Your turn" for stop, "Awaiting input" / "I'm blocked" for permission), and shows a clickable banner that jumps straight to the waiting session. Both phrase lists are config knobs — replace them with whatever you find funnier (jokes, your cat's name, a Star Wars soundboard). One-liner exchanges are skipped via notify_threshold_sec. A finished session you never came back to gets re-nudged at doubling intervals (20, 40, … min) while it sits 🟢 unread — notify_idle_interval_min, off with 0. Requires terminal-notifier; see docs/configuration.md § Notifications to silence one channel without losing the other.

Install

brew install --cask swiftbar               # if not already installed
brew install terminal-notifier             # optional, enables banners + chime
brew install alexey-krylov/claude-agents-bar/claude-agents-bar
claude-agents-bar setup

terminal-notifier is optional — the menu-bar UI works without it, but stop/permission banners and their click-to-jump-to-session behaviour don't fire until it's installed. claude-agents-bar doctor warns when it's missing.

setup symlinks the plugin into SwiftBar's plugins directory, registers the Claude Code hook in ~/.claude/hooks/, and merges (with timestamped backup) hook entries into ~/.claude/settings.json. Idempotent — safe to re-run.

Sessions started after setup populate the sidecar TSV and show live state. Sessions started before will appear (from JSONL mtime) but as plain idle until they emit their next hook event.

Verify everything is wired up:

claude-agents-bar doctor    # jq + python3 + SwiftBar.app, hook
                            # registration, sidecar freshness, editor app

Uninstall

claude-agents-bar teardown
brew uninstall claude-agents-bar

Symlinks and hook entries are removed (a fresh settings.json backup is taken first). The four sidecar files under ~/.claude/ are left in place — they may contain forget/dismiss cutoffs you want to keep.

No Homebrew? See docs/install-manual.md for a git-clone install path.

Hacking on the plugin? Clone the repo instead of brew install-ing — see PLUGIN.md.

Configuration

All knobs are optional — defaults work. To customise, click Tools → Configuration… in the menu (creates the file on first open) and edit it. SwiftBar picks up new values on the next 5 s tick.

The three fields you're most likely to touch:

KeyDefaultMeaning
fresh_minutes60How long a finished session stays 🟢 before auto-promoting to 🔵.
ack_minutes60How long an acknowledged 🔵 session stays before fading to ⚪.
menubar_iconClaude.app glyphPlain glyph, sf:<name>, template:<path>, or image:<path>.

Full reference (~22 fields incl. notification chimes / voice / quiet hours / keep-awake, icon formats, compact mode for notched MacBooks, refresh cadence, sidecar files on disk): docs/configuration.md.

How it works

A Python script polls every 5 seconds. It reads ~/.claude/projects/*/*.jsonl (the transcripts Claude Code already writes — for titles and cwd) plus a small sidecar TSV that a Claude Code hook (hooks/agent-state.sh) updates on every session event (SessionStart, PreToolUse, Stop, …). No daemon, no IPC — the plugin is stateless and rebuilds the menu from disk on every tick.

Without the hooks the plugin still works, but every session looks idle — the state TSV is what distinguishes working / waiting from idle.

Architecture, dev workflow, code style, and how to add submenu actions or new states: PLUGIN.md. Design rationale for the structural choices: docs/adr/.

Troubleshooting

Icon not showing on a notched MacBook. macOS clips menu-bar items behind the notch when the bar fills up. Cheapest fix: enable compact mode ("compact": true in config.json) — drops ~30 px by hiding the icon and swapping 🟡🟢🔵 for narrow ANSI ● bullets. Other fixes: docs/troubleshooting.md.

Plugin appears stuck or empty. Run it standalone — /usr/bin/python3 claude-agents.5s.py | head -40. If that prints the icon line and a session list, the plugin is healthy and only the menu-bar rendering is hiding it. Otherwise: docs/troubleshooting.md.

Contributing

Suggestions and bug reports — open an issue. If you want to make a change, fork the repo and send a PR. PLUGIN.md covers the architecture and dev workflow. User-visible changes go in CHANGELOG.md. For installing or upgrading via a Claude Code agent, see CLAUDE.md.

Ver o original no GitHub

Bom para

Relacionados