Semaphore

Semaphore

Floating traffic light for AI coding agents. Shows when your agent is idle, thinking, or writing files, without switching windows or reading the terminal.

Light	Meaning
Green	Ready for a new task (idle)
Yellow	Thinking / running tools
Red	Writing or editing files

Semaphore is a small always-on-top widget in the system tray. AI tools send activity updates through **hooks**, and Semaphore updates the light.

---

Table of contents

• Download
• Quick start
• Using the app
• Supported tools
• semctl CLI
• Configuration
• How it works
• Architecture
• Development
• Themes & i18n
• Sounds
• Stream Deck
• Stealth mode
• Troubleshooting
• Contributing
• License

---

Download

Pre-built binaries for macOS (Apple Silicon & Intel), Linux, and Windows:

**[Download latest release](https://github.com/lucianodiisouza/semaphore/releases/latest)**

Each release includes:

Asset	Description
Semaphore app	.dmg (macOS), .msi (Windows), .deb or .AppImage (Linux)
semctl	CLI bundled inside the app; copied to ~/.semaphore/bin/ on first run

You don't need a terminal for normal use after install.

**macOS:** If the system says the app is *damaged* or won't open after download, see [macOS Gatekeeper](#macos-gatekeeper-app-is-damaged-or-wont-open) below. The app is not corrupted — macOS blocks unsigned downloads by default.

---

Quick start

1. Download a release for your OS (or build from source)
2. Launch Semaphore. It stays in the system tray and shows the floating widget
3. Complete onboarding (first launch) or open Settings and connect your AI tools