convez.ai
AgenteProdutividadeIntermediário
guan-ops

Agent Signal Bar

guan-ops/Agent-Signal-Bar

Sinais visuais em tempo real para agents IA no macOS

Ver no GitHub
BomPluginScore · de 0 a 100

App nativo macOS que monitora o estado de agentes IA locais (Codex, Claude Code) através de sinais luminosos na barra de menu e na tela. Oferece visualização local-first com semáforos animados, alertas sonoros customizáveis e widget flutuante redimensionável para acompanhamento em tempo real do progresso dos agentes.

Instalação

$npx convez-ai guan-ops/Agent-Signal-Bar

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
71
Forks
9
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v1.6.2
Issues abertas
5
Contribuidores
2

Casos de uso

  • Monitorar status de Claude Code e Codex Desktop sem alternar janelas
  • Acompanhar progresso de scripts IA locais com feedback visual imediato
  • Receber alertas sonoros customizáveis de conclusão e bloqueios de agentes

Veredito

Ferramenta especializada e bem executada para devs que trabalham com agentes IA locais no macOS. Arquitetura local-first elimina dependências externas e a UI com sinais luminosos é intuitiva, mas o escopo é limitado ao ecossistema Apple.

README

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

Agent Signal Bar is a local-first macOS app that uses three red, yellow, and green signal lights in the menu bar and on the desktop to show the current state of local AI agents. It helps you see whether Codex, Claude Code, or a local script is idle, thinking, working, done, waiting for approval, or blocked without switching back to a terminal or editor.

Floating Signal Light

The floating signal light stays visible on the desktop, syncs with the menu bar light, and supports dragging, resizing, vertical or horizontal layouts, a compact running-agent badge, and a small current-session popover. Sound alerts can be configured separately for completion, green flashing, and warning states.

Listen to the bundled New Zealand crossing sounds: green flash sound · completion sound.

Download And Open

For normal use, download the app from GitHub Releases, not from the green Code button. The Code > Download ZIP file is source code and does not contain a ready-to-open app installer.

  1. Open the latest release.
  2. Download AgentSignalBar.dmg.
  3. Open the DMG and drag AgentSignalLight.app to Applications.
  4. Open Agent Signal Bar from Applications.

If macOS blocks the first launch because the build is not notarized yet, right-click the app and choose Open, or use System Settings > Privacy & Security > Open Anyway.

Developers can also download the source code and run ./script/build_and_run.sh.

Menu Bar Panel

Click the menu bar signal light to open either the detailed panel or the simple native-style menu. Both show the current status and live agent activity. The detailed panel keeps the quick actions focused on pausing monitoring, opening settings, and quitting; the simple menu can also show open-agent shortcuts when relevant.

Settings Liquid Glass Comparison

Both images are real screenshots of the current Activity page. The left image shows the normal solid settings window, while the right image shows the default Standard Liquid Glass style with the desktop background participating in the window material. Liquid Glass is on by default and can be adjusted between Standard and Enhanced in General > Liquid glass.

Features

  • macOS menu bar signal light with horizontal and vertical layouts.
  • Floating desktop signal light with drag, resize, badges, current-session popover, and synced animation.
  • Separate sound choices for completion, green flashing, and warning states, including New Zealand crossing sounds.
  • Two visual styles: classic signal board and minimal dots.
  • Menu bar panel with current status, running agents, recent activity, pause/settings actions, and quit.
  • Settings window with Activity, General, Connections, Advanced, and About pages.
  • Codex Desktop activity monitoring without required hooks, plus optional Codex hooks, Claude Code hooks, and generic JSON event input.
  • Multi-session aggregation so permission, failure, and blocked states are not overwritten by normal working states.
  • Local CLI for scripts, automation, and custom agents.
  • Multilingual UI with system-language detection and manual language switching.
  • Customizable light effects, including blink speed, breathing strength, and per-state effect choices.
  • Theme selection and launch at login.
  • No cloud service is required. State files, hooks, and diagnostics stay on your Mac.

Signal Language

Agent stateDefault effectMeaning
Idle idlesteady greenNothing needs attention
Thinking thinkingfast green flashThe agent is reasoning about the task
Working workingslow green flashThe agent is editing files, running tools, or testing
Step done tool_doneslow green flashOne step finished and the workflow may continue
Done donesteady greenThe task is complete and will return to idle shortly
Attention attention / notificationflashing yellowCheck when convenient
Permission permission / permission_requestflashing redApproval is needed now
Blocked blocked / failure / errorfast flashing redImmediate action is needed
Stale stalegray/yellow warningThe state file is old, damaged, or untrusted
Off off / pauseall lights off or static grayMonitoring is paused

Default effect settings:

  • Thinking: fast green flash
  • Working: slow green flash
  • Done: steady green

Effects can be customized in the Advanced page of the settings window.

Light Effect Preview

Aggregation Priority

When multiple agents or sessions are active, the menu bar shows the highest-priority state:

paused > blocked > permission > needs_review > stale > active > completed > ready

Red states are never overwritten by normal work. Yellow attention states are also protected from newer working events. done is visible for 30 seconds by default, then returns to idle.

Quick Start

Build and run:

./script/build_and_run.sh

Verify the app:

./script/build_and_run.sh --verify

Open the settings window for UI verification:

./script/build_and_run.sh --ui-verify

Run local diagnostics:

./script/doctor.sh
./script/doctor.sh --full

Package the app:

./script/package_app.sh --release

Build local zip and DMG artifacts:

./script/package_release.sh

CLI

Install the CLI:

./script/install_cli.sh

Update state:

./scripts/agent-signal idle
./scripts/agent-signal thinking --session codex-main --agent codex
./scripts/agent-signal working --session codex-main --agent codex --event PreToolUse
./scripts/agent-signal permission --session claude-main --agent claude-code --event PermissionRequest
./scripts/agent-signal blocked --session job-1 --agent script --event Failed
./scripts/agent-signal done --session codex-main --agent codex --event Stop

Read state:

./scripts/agent-signal status
./scripts/agent-signal status --json

Reset to idle:

./scripts/agent-signal reset

Wrap any command as an agent run:

./scripts/agent-signal-run \
  --session nightly-build \
  --agent script \
  -- ./run-build.sh

Agent Integration

Codex Desktop can work without manually installing hooks. Keep Monitor Codex Desktop enabled in the app and Agent Signal Bar will read local Codex session logs to detect thinking, working, step-done, and done states. Hooks are optional for Codex Desktop, but they are still useful for Codex CLI/TUI, Codex IDE compatibility, project-scoped automation, Claude Code, and other local agents that report events directly.

Codex Desktop activity comes from the local Codex session log. Normal browser usage does not trigger Agent Signal Bar unless it is part of an active Codex task that is using tools.

Integration verification status:

  • Codex has been tested in real use and is fully verified.
  • Claude Code hook support is implemented, but it has not yet been verified with a live Claude Code workflow.

Install hooks when you need CLI/IDE or Claude Code integration:

./script/install_hooks.py --target all --codex-scope project --dry-run
./script/install_hooks.py --target all --codex-scope project --install

For development, project-scoped Codex hooks are recommended so project-level and user-level hooks do not fire at the same time.

Generic JSON input:

echo '{"event":"AgentStarted","agent":"local-script","session_id":"local-main"}' \
  | ./scripts/generic-agent-signal-hook

echo '{"event":"ApprovalRequired","agent":"local-script","session_id":"local-main"}' \
  | ./scripts/generic-agent-signal-hook

State File

Default state file:

/tmp/agent-signal/status.json

Example:

{
  "schema_version": 1,
  "aggregate": "working",
  "updated_at": "2026-05-28T03:45:00Z",
  "sessions": {
    "codex-main": {
      "agent": "codex",
      "signal": "working",
      "last_event": "PreToolUse",
      "updated_at": "2026-05-28T03:45:00Z"
    }
  },
  "events": [
    {
      "id": "D4204E0A-5B5D-4DFB-A3BC-643E6C7C6F8F",
      "session_id": "codex-main",
      "agent": "codex",
      "signal": "working",
      "event": "PreToolUse",
      "updated_at": "2026-05-28T03:45:00Z"
    }
  ]
}

Environment variables:

export AGENT_SIGNAL_LIGHT_STATE_FILE=/path/to/status.json
export AGENT_SIGNAL_LIGHT_STATE_DIR=/tmp/agent-signal
export AGENT_SIGNAL_LIGHT_EVENT_LIMIT=50
export AGENT_SIGNAL_LIGHT_COMPLETED_TTL_SECONDS=90
export SIGNAL_LIGHT_SESSION_TTL_SECONDS=1800

Project Layout

Sources/
  AgentSignalLight/        macOS app, menu bar, settings window
  AgentSignalLightCore/    state model, aggregation, hook mapping
  AgentSignalLightUI/      signal rendering and icon geometry
  AgentSignalCLI/          agent-signal CLI
scripts/                   CLI wrappers and hook wrappers
script/                    build, install, diagnostics, packaging scripts
docs/                      integration docs, state schema, release checklist
Tests/                     Swift tests

Documentation

License

Source code is licensed under the Apache License 2.0.

Non-code assets use separate terms:

  • Bundled audio files, including the New Zealand crossing sounds, plus app icons, logos, screenshots, GIFs, and marketing artwork are covered by ASSET_LICENSES.md.
  • The Agent Signal Bar name and brand assets are covered by TRADEMARKS.md.

Attribution is recorded in NOTICE.

© 2026 XiongYang Guan (guan-ops)

Ver o original no GitHub

Bom para

Relacionados