{
  "markdown": "# Agent Beacon\n\nAgent Beacon is a local status display for Claude Code and Codex. It shows\nwhether each root session is working, idle, waiting for attention, finished, or\nfailed, while keeping active workers visible. The same 64 × 64 frame appears in\na browser preview, on a Divoom Pixoo-64, or on both.\n\n| One root session working | Three live sessions | Approval needed |\n|---|---|---|\n| <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\"> |\n\n## How it works\n\n```text\nClaude Code / Codex\n        │ local hooks\n        ▼\n agent-beacon emit ──loopback──▶ Agent Beacon service\n                                  ├── browser preview\n                                  └── Pixoo-64\n```\n\nThe hooks send sanitized lifecycle events to a daemon bound to\n`127.0.0.1`. The daemon derives the current state and uses one renderer for\nboth the browser preview and the physical display.\n\n## Requirements\n\n- macOS or Linux\n- Go 1.26.5 and `make`\n- Claude Code, Codex, or both\n- Optional: a Pixoo-64 on the same local network\n\nAll source-relative commands below run from the repository root.\n\n## Install\n\nBuild and install the executable:\n\n```sh\nmake release-install\ncommand -v agent-beacon\n```\n\n`release-install` writes to `$GOBIN` when it is set, or to `$GOPATH/bin`\notherwise. If `command -v` prints nothing, add that install directory to your\n`PATH` before continuing.\n\nCreate the local profile:\n\n```sh\nagent-beacon init\n```\n\n### Claude Code\n\n```sh\nclaude plugin marketplace add ./plugins/claude\nclaude plugin install agent-beacon@agent-beacon --scope user\n```\n\n### Codex\n\n```sh\ncodex plugin marketplace add ./plugins/codex\ncodex plugin add agent-beacon@agent-beacon\n```\n\nOn the next interactive Codex launch, review and trust the Agent Beacon hooks\nso Codex can run them.\n\n### Start Agent Beacon\n\nInstall and start the background service:\n\n```sh\nagent-beacon service install\nagent-beacon service start\n```\n\nTo try it in the foreground, or on Linux without a systemd user service, run:\n\n```sh\nagent-beacon serve\n```\n\nLeave that terminal running. Run `preview` and `demo` from another terminal;\nthey connect to the foreground daemon.\n\nOpen the browser preview first:\n\n```sh\nagent-beacon preview --open\n```\n\nThe preview shows the same rendered frame as the Pixoo. To populate it without\nstarting a coding-agent session, run the built-in scenario:\n\n```sh\nagent-beacon demo\n```\n\nCheck the installed binary, running service, integrations, and display:\n\n```sh\nagent-beacon version\nagent-beacon status\nagent-beacon doctor\n```\n\nThe [Setup guide](docs/guide/setup.md) covers the profile, foreground mode, and\nupgrade checks in more detail.\n\n## Use a Pixoo-64\n\nEdit the `config.toml` created by `agent-beacon init`. For a Pixoo-only display:\n\n```toml\n[display]\ndriver = \"pixoo64\"\nendpoint = \"http://<pixoo-ip>\"\n```\n\nTo keep the browser preview alongside the Pixoo:\n\n```toml\n[display]\ndriver = \"multi\"\nbridge = \"pixoo64\"\nendpoint = \"http://<pixoo-ip>\"\n```\n\nRestart Agent Beacon after changing display settings. If it is running as a\nbackground service:\n\n```sh\nagent-beacon service restart\n```\n\nIf it is running in the foreground, press Ctrl-C in the terminal running\n`agent-beacon serve`, then start it again:\n\n```sh\nagent-beacon serve\n```\n\nAfter either restart, verify the display from another terminal:\n\n```sh\nagent-beacon doctor\n```\n\nSee the [Configuration guide](docs/guide/configuration.md) for the full display\nand profile settings.\n\n## Normal commands\n\n| Command | Purpose |\n|---|---|\n| `agent-beacon status` | Show live sessions, active workers, attention, totals, and display health |\n| `agent-beacon doctor` | Check the installation and print a fix for each fault |\n| `agent-beacon preview --open` | Open the browser preview |\n| `agent-beacon demo` | Run the built-in display scenario |\n| `agent-beacon service restart` | Restart the background service |\n| `agent-beacon service stop` | Stop the background service |\n| `agent-beacon service start` | Start the installed service |\n| `agent-beacon version` | Print the installed build version |\n\n## Display states\n\n<details>\n<summary>See more display states</summary>\n\n| No live sessions | Task completed | Session failure |\n|---|---|---|\n| <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\"> |\n\n</details>\n\n## Privacy and failure behavior\n\nAgent Beacon runs locally and binds its API to loopback. Prompts, replies, task\ntext, tool arguments and output, error text, transcript paths, and full working\ndirectory paths are not stored or forwarded. It does not contact a cloud\nservice. The configured physical display endpoint receives rendered frames and\nthe device-control requests needed to publish and restore the Pixoo. None of the\nwork content listed above goes there.\n\nThe hooks are fail-open: if Agent Beacon is stopped, slow, or broken, they exit\nsilently and successfully so they do not interrupt Claude Code or Codex. The\n[Privacy guide](docs/guide/privacy.md) explains the boundary in plain language.\n\n## Remove Agent Beacon\n\nStop Agent Beacon before removing it. If `agent-beacon serve` is running in the\nforeground, press Ctrl-C in its terminal. If Agent Beacon is running as a\nbackground service, stop and uninstall the service:\n\n```sh\nagent-beacon service stop\nagent-beacon service uninstall\n```\n\nRemove only the integrations you installed. For Claude Code:\n\n```sh\nclaude plugin uninstall agent-beacon@agent-beacon --scope user\nclaude plugin marketplace remove agent-beacon --scope user\n```\n\nFor Codex:\n\n```sh\ncodex plugin remove agent-beacon@agent-beacon\ncodex plugin marketplace remove agent-beacon\n```\n\nThese commands preserve the local Agent Beacon profile and database. To remove\nall Agent Beacon-owned local data after the daemon is stopped, run the separate,\nexplicit purge:\n\n```sh\nagent-beacon purge --yes\n```\n\nThe source install has no package-manager uninstall. Run\n`command -v agent-beacon`, then remove the executable at the path it prints.\n\n## Documentation\n\n- [Setup guide](docs/guide/setup.md) — installation, service setup, displays,\n  verification, and upgrades.\n- [Configuration guide](docs/guide/configuration.md) — profile location,\n  settings, and reload behavior.\n- [Privacy guide](docs/guide/privacy.md) — collected data and the fail-open\n  guarantee.\n- [Troubleshooting guide](docs/guide/troubleshooting.md) — faults reported by\n  `agent-beacon doctor`.\n- [Documentation bundle](docs/index.md) — the technical contracts and complete\n  product documentation.\n",
  "bytes": 7145,
  "sha": "f916818833adee4eb25ec8b8ecd837b055d768ad0f2a8f0875afb45369eb0893",
  "repo_slug": "dacebt/agent-beacon",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_dacebt_agent_beacon_docs_index_md_bedb72b2/readme"
}