Agent Beacon — Documentation Bundle
Bundle OKF 0.2 · 24 conceitos · dacebt/agent-beacon
Open source Repository Open in the app JSON README (API)
About
# Agent Beacon — Documentation Bundle
Local Claude Code and Codex activity visualization for the Divoom Pixoo-64. These documents are the project's authority. Start with the binding cores — [Domain Model](./DOMAIN.md) and [Architecture](./ARCHITECTURE.md) — then read the contract that covers the surface you are changing.
- [Direction](./direction/index.md) — Active WSD session boundaries and persistent feature direction.
## Product definition
- [Scope](./SCOPE.md) — What Agent Beacon is, what it deliberately is not, and the measures that define success for the first release. *(binding)*
- [Domain Model](./DOMAIN.md) — The bound vocabulary of Agent Beacon — sessions, workers, claims, attention, totals — and the algorithm that derives display state from them. *(binding)*
## Contracts
- [Architecture](./ARCHITECTURE.md) — Component responsibilities, the module walls that must survive contributors, the execution model, failure isolation, and performance budgets. *(binding)*
- [Event
Details
- Kind
- OKF bundles
- Topic
- No topic detected
- Publisher
- dacebt
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Stars
- 1
- Last push
- 2026-08-28T23:59:21Z
- Repository state
- ativo
- Language
- Go
- Added
- 2026-09-09 12:03:57
- Updated
- 2026-09-09 12:03:57
- Origin id
dacebt/agent-beacon:docs/index.md
README
# Agent Beacon
Agent Beacon is a local status display for Claude Code and Codex. It shows
whether each root session is working, idle, waiting for attention, finished, or
failed, while keeping active workers visible. The same 64 × 64 frame appears in
a browser preview, on a Divoom Pixoo-64, or on both.
| One root session working | Three live sessions | Approval needed |
|---|---|---|
| <img src="docs/assets/readme/g02-one-claude-root-working.png" width="256" height="256" alt="Agent Beacon showing one Claude root session working"> | <img src="docs/assets/readme/g06-three-roots.png" width="256" height="256" alt="Agent Beacon showing three live root sessions"> | <img src="docs/assets/readme/g08-approval-alert.png" width="256" height="256" alt="Agent Beacon showing a root session blocked on approval"> |
## How it works
```text
Claude Code / Codex
│ local hooks
▼
agent-beacon emit ──loopback──▶ Agent Beacon service
├── browser preview
└── Pixoo-64
```
The hooks send sanitized lifecycle events to a daemon bound to
`127.0.0.1`. The daemon derives the current state and uses one renderer for
both the browser preview and the physical display.
## Requirements
- macOS or Linux
- Go 1.26.5 and `make`
- Claude Code, Codex, or both
- Optional: a Pixoo-64 on the same local network
All source-relative commands below run from the repository root.
## Install
Build and install the executable:
```sh
make release-install
command -v agent-beacon
```
`release-install` writes to `$GOBIN` when it is set, or to `$GOPATH/bin`
otherwise. If `command -v` prints nothing, add that install directory to your
`PATH` before continuing.
Create the local profile:
```sh
agent-beacon init
```
### Claude Code
```sh
claude plugin marketplace add ./plugins/claude
claude plugin install agent-beacon@agent-beacon --scope user
```
### Codex
```sh
codex plugin marketplace add ./plugins/codex
codex plugin add agent-beacon@agent-beacon
```
On the next interactive Codex launch, review and trust the Agent Beacon hooks
so Codex can run them.
### Start Agent Beacon
Install and start the background service:
```sh
agent-beacon service install
agent-beacon service start
```
To try it in the foreground, or on Linux without a systemd user service, run:
```sh
agent-beacon serve
```
Leave that terminal running. Run `preview` and `demo` from another terminal;
they connect to the foreground daemon.
Open the browser preview first:
```sh
agent-beacon preview --open
```
The preview shows the same rendered frame as the Pixoo. To populate it without
starting a coding-agent session, run the built-in scenario:
```sh
agent-beacon demo
```
Check the installed binary, running service, integrations, and display:
```sh
agent-beacon version
agent-beacon status
agent-beacon doctor
```
The [Setup guide](docs/guide/setup.md) covers the profile, foreground mode, and
upgrade checks in more detail.
## Use a Pixoo-64
Edit the `config.toml` created by `agent-beacon init`. For a Pixoo-only display:
```toml
[display]
driver = "pixoo64"
endpoint = "http://<pixoo-ip>"
```
To keep the browser preview alongside the Pixoo:
```toml
[display]
driver = "multi"
bridge = "pixoo64"
endpoint = "http://<pixoo-ip>"
```
Restart Agent Beacon after changing display settings. If it is running as a
background service:
```sh
agent-beacon service restart
```
If it is running in the foreground, press Ctrl-C in the terminal running
`agent-beacon serve`, then start it again:
```sh
agent-beacon serve
```
After either restart, verify the display from another terminal:
```sh
agent-beacon doctor
```
See the [Configuration guide](docs/guide/configuration.md) for the full display
and profile settings.
## Normal commands
| Command | Purpose |
|---|---|
| `agent-beacon status` | Show live sessions, active workers, attention, totals, and display health |
| `agent-beacon doctor` | Check the installation and print a fix for each fault |
| `agent-beacon preview --open` | Open the browser preview |
| `agent-beacon demo` | Run the built-in display scenario |
| `agent-beacon service restart` | Restart the background service |
| `agent-beacon service stop` | Stop the background service |
| `agent-beacon service start` | Start the installed service |
| `agent-beacon version` | Print the installed build version |
## Display states
<details>
<summary>See more display states</summary>
| No live sessions | Task completed | Session failure |
|---|---|---|
| <img src="docs/assets/readme/g01-no-live-sessions.png" width="256" height="256" alt="Agent Beacon showing no live sessions and today's totals"> | <img src="docs/assets/readme/g14-task-completed.png" width="256" height="256" alt="Agent Beacon showing a completed task"> | <img src="docs/assets/readme/g18-session-failure.png" width="256" height="256" alt="Agent Beacon showing a failed root session"> |
</details>
## Privacy and failure behavior
Agent Beacon runs locally and binds its API to loopback. Prompts, replies, task
text, tool arguments and output, error text, transcript paths, and full working
directory paths are not stored or forwarded. It does not contact a cloud
service. The configured physical display endpoint receives rendered frames and
the device-control requests needed to publish and restore the Pixoo. None of the
work content listed above goes there.
The hooks are fail-open: if Agent Beacon is stopped, slow, or broken, they exit
silently and successfully so they do not interrupt Claude Code or Codex. The
[Privacy guide](docs/guide/privacy.md) explains the boundary in plain language.
## Remove Agent Beacon
Stop Agent Beacon before removing it. If `agent-beacon serve` is running in the
foreground, press Ctrl-C in its terminal. If Agent Beacon is running as a
background service, stop and uninstall the service:
```sh
agent-beacon service stop
agent-beacon service uninstall
```
Remove only the integrations you installed. For Claude Code:
```sh
claude plugin uninstall agent-beacon@agent-beacon --scope user
claude plugin marketplace remove agent-beacon --scope user
```
For Codex:
```sh
codex plugin remove agent-beacon@agent-beacon
codex plugin marketplace remove agent-beacon
```
These commands preserve the local Agent Beacon profile and database. To remove
all Agent Beacon-owned local data after the daemon is stopped, run the separate,
explicit purge:
```sh
agent-beacon purge --yes
```
The source install has no package-manager uninstall. Run
`command -v agent-beacon`, then remove the executable at the path it prints.
## Documentation
- [Setup guide](docs/guide/setup.md) — installation, service setup, displays,
verification, and upgrades.
- [Configuration guide](docs/guide/configuration.md) — profile location,
settings, and reload behavior.
- [Privacy guide](docs/guide/privacy.md) — collected data and the fail-open
guarantee.
- [Troubleshooting guide](docs/guide/troubleshooting.md) — faults reported by
`agent-beacon doctor`.
- [Documentation bundle](docs/index.md) — the technical contracts and complete
product documentation.