convez.ai
HookProdutividadeIntermediário
yhz61010

TrafficLight4AI

yhz61010/trafficlight4ai

Semáforo visual para monitorar status de assistentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Indicador visual de status em tempo real para ferramentas de IA (Claude, Copilot, Codex). Exibe um semáforo flutuante (vermelho = processando, amarelo = aguardando confirmação, verde = concluído) integrado via hooks CLI. Construído em C++17/Qt6 para Linux e Windows.

Instalação

$npx convez-ai yhz61010/trafficlight4ai

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

Casos de uso

  • Monitorar progresso de AI coding assistants em tempo real
  • Indicar visualmente quando IA está pensando, aguardando entrada ou pronta
  • Integrar status de ferramentas de IA com workflows de desenvolvimento

Veredito

Ferramenta bem pensada que resolve um problema real de UX ao usar assistentes de IA em terminal. Implementação sólida em C++/Qt com suporte multiplataforma e integração via IPC simples, ideal para quem trabalha intensivamente com AI coding tools.

README

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

trafficlight4ai

A visual traffic light status indicator for AI coding tools (Codex, Claude Code, Qoder CN, Copilot, and more).

中文文档

What It Does

When your AI coding assistant is running in the terminal, trafficlight4ai shows you what's happening at a glance:

  • Red (blinking) — AI is working (tool calls, subagents, thinking)
  • Yellow (blinking) — AI needs your confirmation (permission requests, notifications)
  • Green (steady) — Done, waiting for your next prompt

It displays as a small floating always-on-top window + system tray icon on your desktop.

How It Works

AI Tool Hooks → tl4ai-ctl (CLI) → local IPC socket → trafficlight4ai (GUI)

Your AI tool's hook system triggers tl4ai-ctl red/yellow/green at the right moments. The GUI updates instantly.

Download

Prebuilt archives are available from GitHub Releases:

Linux distro packages are dynamically linked and target the named distribution family. For other distributions, use the AppImage or build from source using docs/BUILD.md.

On Windows (10 or later), run bin/trafficlight4ai.exe. It is built as a GUI application and should not open a console window. Use bin/tl4ai-ctl.exe red/yellow/green from PowerShell, cmd, or AI tool hooks to change the light state. If Windows reports missing MSVC runtime DLLs, install the Microsoft Visual C++ Redistributable 2022 x64.

Build From Source

See docs/BUILD.md for Linux and Windows prerequisites, build commands, packaging notes, and verification steps.

Source builds are verified in GitHub Actions (build.yml) on Ubuntu 24.04, Fedora 41, Arch Linux latest, openSUSE Leap 15.6, AppImage (Ubuntu 22.04), and Windows. The workflow runs automatically on pull requests to main, and can be triggered manually to build a single platform or all platforms. The build guide lists distribution-specific packages and the openSUSE GCC 13 requirement.

The build produces two executables:

ExecutablePathDescription
trafficlight4aibuild/src/trafficlight4aiQt GUI main program — floating window + system tray icon, embeds IPC server to receive state commands
tl4ai-ctlbuild/tools/tl4ai-ctlLightweight CLI — sends RED/YELLOW/GREEN commands to the GUI via local IPC socket

Quick Start

1. Run the GUI

./build/src/trafficlight4ai &

2. Make tl4ai-ctl available to hooks

Hooks need to find tl4ai-ctl. Choose one of the following:

Option A — Use absolute path directly in hook commands (no installation needed):

Replace tl4ai-ctl with the full path in step 3, e.g.:

/home/you/trafficlight4ai/build/tools/tl4ai-ctl red

Option B — Add to PATH (so hooks can use the short name tl4ai-ctl):

# Symlink to a directory already in PATH
sudo ln -s "$(pwd)/build/tools/tl4ai-ctl" /usr/local/bin/tl4ai-ctl

# Or copy to ~/.local/bin (no sudo needed, make sure ~/.local/bin is in PATH)
cp build/tools/tl4ai-ctl ~/.local/bin/

3. Configure hooks for your AI tool

See docs/HOOKS.md for hooks configuration examples for each supported AI tool (Codex, Claude Code, Qoder CN, Copilot). You can also view and edit these templates directly in the Settings dialog.

4. Test manually

tl4ai-ctl red      # Red light blinks
tl4ai-ctl yellow   # Yellow light blinks
tl4ai-ctl green    # Green light steady

Features

  • Floating window — Draggable, always-on-top, remembers position
  • System tray icon — Color changes with state, right-click menu
  • Settings dialog — Live preview, cancel to undo
    • AI tool selection (Codex / Claude Code / Qoder CN / Copilot)
    • Timeout auto-idle (default 5 min, 0 to disable)
    • Window size (extra small / small / medium / large / extra large)
    • Animation mode (breathing / classic blink)
    • Animation period (200–5000ms)
    • Socket path
  • Strategy pattern — Easy to add new AI tools (implement AiToolStrategy, register in AiToolRegistry)
  • Sound notifications — Plays sound on yellow (confirmation needed) and green (done), supports WAV/MP3/OGG with system beep fallback
  • i18n — English (default), Chinese, Japanese, switchable at runtime
  • Lightweight CLI — tl4ai-ctl uses Qt Core/Network and QLocalSocket for cross-platform local IPC

Configuration

Config file: ~/.config/trafficlight4ai/config.json

{
  "language": "en",
  "aiTool": "codex",
  "timeoutSec": 300,
  "window": {
    "size": "medium",
    "posX": 20,
    "posY": 20
  },
  "animation": {
    "mode": "breathing",
    "periodMs": 1000
  },
  "socket": {
    "path": "$XDG_RUNTIME_DIR/trafficlight4ai.sock"
  },
  "sound": {
    "yellowEnabled": true,
    "greenEnabled": true,
    "yellowFile": "",
    "greenFile": ""
  }
}

Socket path/name can also be overridden via TL4AI_SOCKET environment variable.

Tests

cmake -B build -DCMAKE_BUILD_TYPE=Debug && cmake --build build -j$(nproc) && cd build && ctest --output-on-failure
or
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)
cd build && ctest --output-on-failure

Adding a New AI Tool

trafficlight4ai uses a strategy pattern to support multiple AI tools. To add a new one:

  1. Create a strategy class in src/AiToolStrategy.h — inherit from AiToolStrategy and implement:

    • id() — unique identifier (e.g. "my-tool")
    • displayName() — name shown in the Settings dialog (e.g. "My Tool")
    • defaultTimeoutSec() — auto-idle timeout in seconds
    • hooksTemplate() — recommended hooks config JSON for this tool
  2. Register it in AiToolRegistry::strategies() (same file) — add a static instance and append its pointer to the list.

  3. Rebuild — the new tool will appear in the Settings dialog's AI tool dropdown and its hooks template will be available via "View Recommended Hooks Config".

No changes are needed to IPC, state machine, or GUI code — the strategy pattern handles everything.

License

MIT

Ver o original no GitHub

Bom para

Relacionados