convez.ai
AgenteUtilidadesIniciante
eddykwang

Agent Light

eddykwang/agent-light

Monitore agentes de IA locais na barra de menu do macOS

Ver no GitHub
InicialPluginScore · de 0 a 100

Aplicativo nativo macOS para barra de menu que monitora agentes de IA rodando localmente (Codex e Claude Code). Exibe status em tempo real com semáforo (verde=trabalhando, amarelo=aguardando entrada, vermelho=erro, cinza=inativo) sem necessidade de hooks ou permissões extras.

Instalação

$npx convez-ai eddykwang/agent-light

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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 dias
Versão
v0.1.7
Issues abertas
0
Contribuidores
1

Casos de uso

  • Monitorar múltiplas sessões de Claude Code/Codex rodando em background
  • Receber notificações quando agentes terminam ou falham
  • Verificar status de agentes sem trocar de janela

Veredito

Ferramenta focada e bem-executada para um caso de uso específico: monitoramento leve de agentes locais. Ideal para desenvolvedores que rodam múltiplos agentes em background, mas tem escopo restrito ao ecossistema macOS.

README

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

Agent Light

A tiny macOS menu bar app for keeping an eye on background coding agents.

Agent Light watches local Codex and Claude Code sessions and turns them into a simple traffic-light signal in your menu bar: working, idle, failed, or unknown. It is built for the moment when you have several agents running in the background and you do not want to keep switching windows just to know whether one of them finished, failed, or is still busy.

Table of Contents

Install

With Homebrew:

brew tap eddykwang/tap
brew install --cask agent-light

Or download the latest zip from GitHub Releases, unzip it, and move Agent Light.app to /Applications.

Current release builds are unsigned and not notarized, so macOS may show an unidentified developer warning the first time you open the app.

Screenshots

Features

  • Native macOS menu bar indicator with vertical or horizontal traffic-light layouts.
  • Automatic Codex detection through local rollout files.
  • Automatic Claude Code detection through local transcript files.
  • Optional Claude Code hooks mode for more precise permission, input, and completion status.
  • Read-only liveness checks using file handles, modification times, and local process metadata.
  • Optional macOS notifications for attention states, individual session completions, and all-agents-idle transitions.
  • Launch-at-login support.
  • No hooks required for the default Codex or Claude Code support path.

Status Colors

ColorMeaning
GreenAt least one agent is working normally.
YellowAn agent needs permission or input.
RedAn agent failed or hit an error.
Dim/offAgents are idle or complete.
GrayNo current status could be determined.

When multiple sessions are visible, the aggregate menu bar status still prefers failure, then input, then working, then idle.

How It Works

Agent Light is split into two local processes:

  1. Agent Light.app is the menu bar app bundle. Its AgentTrafficLights executable reads a shared status file and renders the icon, popover, settings, and notifications.
  2. AgentStatusCollector is started by the app. It scans local agent artifacts, classifies sessions, filters stale ones, and writes:
~/.agent-traffic-lights/status.json

For Codex, the collector scans:

~/.codex/sessions/**/rollout-*.jsonl

For Claude Code, the collector scans:

~/.claude/projects/**/*.jsonl

Codex usually keeps live rollout files open, so the collector can use lsof as an accurate liveness signal. Claude Code closes transcript files between writes, so the collector combines recent transcript updates with read-only local process checks scoped to the same workspace.

Claude Code can also be switched to optional hooks mode during onboarding or from Settings... > Claude Code. In that mode Agent Light adds local Claude Code command hooks that call the bundled AgentClaudeHook helper. The helper receives Claude Code lifecycle events and writes compact status metadata under:

~/.agent-traffic-lights/claude-hooks

Hooks improve needsInput and completion detection for Claude Code. They do not send prompts, tool inputs, model responses, or transcript content to Agent Light. New hook settings apply to new Claude Code sessions; restart existing Claude Code sessions after installing or removing hooks.

Privacy

Everything runs locally on your Mac.

  • The app does not call Codex, Claude Code, or any model API.
  • The app does not send telemetry.
  • The app does not modify agent transcripts or rollout files.
  • The app does not add anything to an agent's context window.
  • Default support does not require installing Codex or Claude Code hooks.
  • Optional Claude Code hooks store status metadata only, locally on your Mac.

The collector reads local agent metadata and writes a compact local status JSON file for the menu bar app to display.

Requirements

  • macOS 14 or newer
  • Swift 5.10
  • Xcode Command Line Tools

Releases

Download the latest build from the latest release.

GitHub release builds are currently unsigned and not notarized. The release zip uses an ad-hoc signature only to keep the app bundle internally valid.

Because the app is not Developer ID signed, macOS may show an unidentified developer warning the first time you open it. This is expected for the current early release builds.

Create a local release zip:

./script/package_release.sh v0.1.3

Tagging a version also publishes the unsigned zip through GitHub Actions:

git tag v0.1.3
git push origin v0.1.3

Run Locally

Build and launch a local app bundle:

./script/build_and_run.sh run

The script creates:

dist/Agent Light.app

You can move that app bundle to /Applications if you want launch-at-login to behave like a normal installed macOS app.

Development

Run the test suite:

swift test

Build without launching:

swift build

Verify that the app bundle launches:

./script/build_and_run.sh verify

Configuration

Open Settings... from the menu bar popover to change:

  • traffic-light orientation
  • Claude Code default or hooks-based status detection
  • shared status file path
  • attention notifications
  • individual session completion notifications
  • all-agents-idle completion notifications
  • launch at login

The menu bar popover also shows the current Claude Code mode. Click CC mode: ... to jump straight to the Claude Code settings tab.

The default status file path is:

~/.agent-traffic-lights/status.json

Limitations

  • Codex approval prompts are not reliably represented in rollout JSONL, so they cannot always be inferred as needsInput from rollout files alone.
  • Claude Code transcript-only mode is best-effort for permission prompts. Use the recommended Claude Code hooks mode from onboarding or Settings... > Claude Code for more precise needsInput and completion status.
  • New Claude Code hook settings apply to new Claude Code sessions. Start a new Claude Code session after installing, removing, or changing hooks.
  • If you move the app bundle after installing Claude Code hooks, install hooks again so Claude Code points at the new app path.
  • The app currently targets macOS only.

Repository Notes

Local agent state is intentionally ignored by Git. Files such as .codex/, .claude/, .agents/, .superpowers/, and CLAUDE.md are treated as local workspace state rather than project source.

License

MIT

Ver o original no GitHub

Bom para

Relacionados