TrafficLight4AI
yhz61010/trafficlight4ai
Semáforo visual para monitorar status de assistentes de IA
Ver no GitHubIndicador 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/trafficlight4ai1 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
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:
trafficlight4ai-0.2.1-windows-amd64.zip— Windows build with Qt runtime files bundled bywindeployqt.trafficlight4ai-0.2.1-linux-amd64.deb— Ubuntu/Debian package.trafficlight4ai-0.2.1-fedora-amd64.rpm— Fedora package.trafficlight4ai-0.2.1-opensuse-amd64.rpm— openSUSE Leap package.trafficlight4ai-0.2.1-arch-amd64.pkg.tar.zst— Arch Linux package.trafficlight4ai-0.2.1-linux-amd64.AppImage— generic Linux AppImage.SHA256SUMS.txt— checksums for release archives.
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:
| Executable | Path | Description |
|---|---|---|
trafficlight4ai | build/src/trafficlight4ai | Qt GUI main program — floating window + system tray icon, embeds IPC server to receive state commands |
tl4ai-ctl | build/tools/tl4ai-ctl | Lightweight 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 inAiToolRegistry) - 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-ctluses Qt Core/Network andQLocalSocketfor 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:
-
Create a strategy class in
src/AiToolStrategy.h— inherit fromAiToolStrategyand implement:id()— unique identifier (e.g."my-tool")displayName()— name shown in the Settings dialog (e.g."My Tool")defaultTimeoutSec()— auto-idle timeout in secondshooksTemplate()— recommended hooks config JSON for this tool
-
Register it in
AiToolRegistry::strategies()(same file) — add a static instance and append its pointer to the list. -
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