Beacon
======

A local agent status tracking and tmux notification tool.
Agent lifecycle hooks write a small bounded JSON snapshot, tmux renders
it, notifications surface events, and `beacon jump` returns to the most
recently completed pane.

Beacon observes the current machine only. It does not schedule tasks,
own tmux sessions, or require any orchestration service. Multiple
machines run independent instances.


Features
--------

  * Agent lifecycle hooks (prompt, stop, notification, permission)
  * tmux status-right rendering: CPU, memory, process count, disk
  * Per-pane / per-window / per-session memory aggregation
  * Working / waiting / blocked / completed status tracking
  * Jump to the last completed live pane
  * macOS and Linux desktop notifications with click-to-jump
  * launchd (macOS) and systemd (Linux) service management
  * No network, database, or model calls


Build
-----

    go build ./cmd/beacon


Install
-------

Requirements: Go 1.26+ and tmux.

    ./install.sh
    beacon doctor

The install script builds the Go binary, installs it to
~/.local/lib/beacon/, symlinks it to ~/.local/bin/beacon, and sets up
the daemon service (launchd on macOS, systemd on Linux).


Quick start
-----------

  1. Start the daemon:

       beacon daemon start

  2. Add hooks to your agent config (e.g. Claude Code):

       {
         "hooks": {
           "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "beacon hook prompt"}]}],
           "Stop": [{"hooks": [{"type": "command", "command": "beacon hook stop"}]}]
         }
       }

  3. Add to tmux:

       set -g status-right '#(beacon status-tmux "#{client_width}" "#{status-bg}" "#{session_name}" "#{window_index}" "#{pane_id}" "#{window_id}")'
       bind-key P run-shell 'beacon jump'

  4. Report status from any agent or script:

       beacon report working 'running tests'
       beacon report completed 'tests passed'


Commands
--------

    beacon                      show status
    beacon daemon start         start the daemon
    beacon daemon stop          stop the daemon
    beacon daemon status        check daemon status
    beacon report <state> [msg] report agent state
    beacon status-tmux [args]   render status for tmux (read-only)
    beacon jump [pane_id]       jump to last completed pane
    beacon doctor               check daemon, socket, and cache
    beacon reset                clear all agent state


Configuration
-------------

State: ${XDG_DATA_HOME:-~/.local/share}/beacon/panes.json
Socket: ${XDG_RUNTIME_DIR:-/tmp}/beacon.sock

The daemon samples metrics in three tiers:

    Fast       4s    CPU, memory pressure, process count
    Footprint  10s   per-pane / window / session tmux memory
    Slow       60s   root disk usage


Development
-----------

    go test ./...           run all tests
    go test -race ./...     run with race detector
    go build ./cmd/beacon   build the binary


License
-------

MIT