Beacon

Stop shipping broken code. Know your deploy status instantly.

Persistent daemon that auto-discovers your repos and monitors every CI/CD deploy.
GitHub polling · Telegram alerts · Waybar widget · Claude Code integration · Zero config.

---

The Problem

You git push, switch tasks, and the deploy silently fails. You keep coding on broken code. Hours later — a cascade of errors.

With AI agents (Claude Code, Cursor, Copilot) it's worse: they keep generating code on top of a failed deploy without knowing.

The Fix

Push from anywhere → Beacon daemon detects it → polls GitHub Actions →
  ✅ Success → Telegram + Waybar green → keep working
  ❌ Failed  → Telegram + Waybar red → Claude Code stops and warns you

No hooks to install per-repo. No config. Beacon auto-discovers repos from your deploy history and polls GitHub every 60s.

---

Quick Start

git clone https://github.com/Blysspeak/beacon && cd beacon && bash install.sh

What the installer does (6 steps)

1. Builds/downloads the binary for your platform
2. Starts systemd daemon — persistent, auto-restarts
3. Installs Claude Code hooks — PreToolUse (warn on fail) + PostToolUse (enqueue push)
4. Connects Telegram — token from @beacon_github_bot
5. Waybar widget (optional) — real-time status bar
6. Done — zero config after install

Or install manually:

cargo install beacon && beacon install

---

How It Works

                    ┌──────────────────────────────┐
                    │    beacon daemon (systemd)    │
                    │    always running              │
                    └──────────┬───────────────────┘
                               │
           ┌───────────────────┼───────────────────┐
           ↓                   ↓                   ↓
     GitHub Poller       Queue Watcher        Notifications
     (every 60s)         (hooks, instant)          │
           │                   │          ┌────────┼────────┐
           └─────────┬─────────┘          ↓        ↓        ↓
                     ↓               📱 Telegram  📊 Waybar  🤖 Claude
              Track workflow                                   Code

Two detection modes — zero config:

Mode	Latency	How it works
GitHub Poller	~60s	Daemon polls GitHub Actions for all auto-discovered repos
Hook (Claude Code)	instant	PostToolUse hook catches git push in Claude sessions

Step	What happens
Push from anywhere	Poller detects new workflow run within 60s
Push via Claude Code	Hook enqueues immediately (< 10ms)
Deploy completes	Writes result, sends Telegram, updates Waybar
Deploy failed	Claude Code sees warning before next action

---

Features

Telegram Notifications

beacon remote connect <TOKEN>   # get token from /start in @beacon_github_bot
beacon remote test              # verify connection

✅ Deploy SUCCESS Repo: myapp Branch: main Workflow: Deploy Backend

❌ Deploy FAILED Repo: myapp Branch: main Failed: deploy (failure)

Claude Code Integration

When a deploy fails, Claude sees this before every action:

⚠️  DEPLOY FAILED — owner/myapp (main)
   Workflow: Deploy Backend
   Failed: deploy (failure)
   Fix the deploy issue before continuing.

Claude stops and helps you fix it instead of piling code on a broken build.

Waybar Widget

Real-time in your status bar. No polling — instant signal.

✓ myapp/Deploy Backend      ← green
✗ myapp/Deploy Frontend     ← red
◉ myapp/Deploy Backend      ← yellow (in progress)

Click → opens GitHub Actions run. Tooltip shows full details.

GitHub Polling (Auto-Discovery)

Beacon automatically discovers repos from your deploy history and polls GitHub Actions for new workflow runs. Push from terminal, IDE, GitHub web — Beacon catches it.

beacon poll list                  # see watched repos
beacon poll add owner/repo        # add repo manually
beacon poll remove owner/repo     # remove repo
beacon poll interval 30           # poll every 30s (default 60s)

Persistent Daemon

Runs as a systemd user service. Always on, auto-restarts.

systemctl --user status beacon     # status
journalctl --user -u beacon -f     # live logs

---

Commands

Command	Description
beacon push [args]	git push + queue for monitoring
beacon status	Last deploy result
beacon status --json	Machine-readable output
beacon log	Deploy history
beacon tui	Interactive deploy dashboard
beacon poll list	Show watched repos (configured + auto-discovered)
beacon poll add <repo>	Add repo to watch list
beacon poll remove <repo>	Remove repo from watch list
beacon poll interval <sec>	Set poll interval (min 10s)
beacon remote connect	Connect Telegram
beacon remote test	Test Telegram
beacon watch	Manual foreground monitor
beacon notify	Enqueue current repo (used by hooks)
beacon daemon	Run daemon (managed by systemd)
beacon install	Setup hooks + daemon
beacon uninstall	Remove everything

Configuration

~/.beacon/
├── config.json        # Telegram + poll config
├── last_deploy.json   # Last deploy status (mailbox)
├── history.jsonl      # Full deploy history
├── queue/             # Push events for daemon (file-based IPC)
└── daemon.log         # Daemon logs (if not using systemd)

Env Variable	Description
GITHUB_TOKEN	GitHub API token (falls back to gh auth token)
BEACON_API_URL	Custom Beacon Bot API URL

Roadmap

• GitHub Actions provider
• Telegram notifications
• Claude Code hooks (PreToolUse + PostToolUse)
• Waybar widget with instant signal refresh
• Persistent systemd daemon
• Interactive installer with ASCII banner
• beacon log — deploy history
• Interactive TUI dashboard
• GitHub polling with auto-discovery (no per-repo setup)
• Railway / Vercel / Fly.io providers
• Webhook mode (replace polling)

Contributing

git clone https://github.com/Blysspeak/beacon
cd beacon
cargo build
cargo test

License

MIT — use it however you want.