🛰️ Beacon

Real-time presence & collision-avoidance for parallel AI coding agents

Run two, five, ten Claude Code sessions on the same repo at once — and never let them clobber each other's work again.

The problem

Running multiple AI coding agents in parallel is the new normal — one session refactors the API, another writes tests, a third bumps configs. It's a huge speedup, until two of them edit the same file, or one runs git checkout / git stash and silently yanks the files out from under the others. You discover the collision only after work is lost.

Agents are flying blind. They can't see each other.

Related MCP server: Claude Halla

What Beacon does

Beacon is a tiny local service that gives every agent a shared, real-time picture of who is touching what — and warns them the instant two of them overlap.

• 👀 Mutual awareness — every session reports what it's editing; others can see it live.

• ⚡ Collision warnings, in-context — when an agent is about to edit a file another agent is already in, Beacon injects a one-line heads-up into that agent's own context, before the edit.

• 🔪 Guards risky shared-tree ops — checkout / reset --hard / stash / rebase / clean, and git add -A / commit -a (which sweep up another agent's uncommitted work), while another session is editing the tree → the agent is warned (or asked to confirm).

• 🔁 Flags redundant builds/deploys — if a build or deploy is already running in a directory, a second agent kicking off another one is warned that it's just burning CPU/Docker. Parallel is fine; redundant is wasteful.

• 📊 Live dashboard — every active agent in real time, color-coded per session, with per-row details, a light/dark toggle, optional grouping of edits by session or conversation turn, and a Settings panel (update checks, start-on-login, per-day log viewer).

• 🪶 Weightless & invisible — zero dependencies, 100% local, and it never blocks your work. No conflict? You never notice it's there.

Safe by design: Beacon is advisory. It fails open — if the daemon is down or anything errors, your session behaves exactly as if Beacon weren't installed. It never denies an edit by default, and in the common (no-overlap) case it adds zero tokens to your agent's context. Nothing leaves your machine — see PRIVACY.md.

Quick start

Pick the install that matches how you use Beacon. Both talk to the same local daemon, and both can be installed at once — Beacon suppresses duplicate reports at runtime.

Claude Code — install the plugin (recommended)

/plugin marketplace add a1473838623/agent-beacon
/plugin install beacon@agent-beacon

That is the whole setup. The plugin brings the hooks and the MCP server, and the daemon lazy-starts itself on the first edit — nothing else to run. Beacon shows up under /plugin and /mcp, and you can disable it from there without editing any config file.

Claude desktop app — upload the plugin

The desktop app has no /plugin terminal panel. Add the marketplace from its plugin browser, or upload a plugin archive directly under Settings → Plugins → Add → Upload local plugin. Build the archive with:

npm run pack:plugin      # → beacon-plugin.zip

It uses git archive, so the plugin files sit at the archive root (.claude-plugin/ plugin.json directly inside, not nested in a folder), which is what the dialog expects.

Or skip the build: every tagged release attaches beacon-plugin.zip, so you can download one from Releases and upload that.

The same archive works from the CLI, with no install and no marketplace — Claude Code fetches it at startup and loads it for that session only:

claude --plugin-url https://github.com/a1473838623/agent-beacon/releases/latest/download/beacon-plugin.zip

A local copy works too: claude --plugin-dir ./beacon-plugin.zip.

Uploading a build whose plugin name matches one you already installed replaces that install in place — the app reuses the existing version directory rather than creating a new one, so the recorded install path can still name the old version while the contents are new. Harmless, but prefer the marketplace when you have one: a later marketplace update will otherwise overwrite your upload.

Codex — install the plugin

codex plugin marketplace add a1473838623/agent-beacon

Then install beacon from codex /plugins, and run /hooks to trust its hooks. Same hooks, same MCP server, same daemon as the Claude Code plugin.

CLI — for the beacon command, the dashboard, and non-Claude-Code agents

One command, any platform:

npm i -g beacon-agents

Then:

beacon init         # GLOBAL by default — every project on this machine is covered
beacon start -d     # start the local daemon (background)
open http://127.0.0.1:4517

Windows: npm i -g writes into Node's global prefix, which sits under C:\Program Files for installer- and nvm-based setups — so it fails with EPERM unless you run as Administrator. If that happens, use the installer instead. It needs no elevation: it installs under %LOCALAPPDATA% and puts a shim on your user PATH.

irm https://raw.githubusercontent.com/a1473838623/agent-beacon/main/install.ps1 | iex

Working on Beacon itself? Clone and npm link instead:

git clone https://github.com/a1473838623/agent-beacon.git && cd agent-beacon && npm link

The npm package is beacon-agents, not agent-beacon. npm normalizes package names by stripping punctuation, which collides with an unrelated, actively maintained package called agentbeacon. The repository, the Claude Code plugin, the marketplace and the beacon command are all unaffected — only npm install takes the different name.

Every new Claude Code session on this machine now reports activity automatically — no per-project steps, no per-session steps, no prompts to remember.

Open a second session, have both edit the same file, and watch the overlap light up on the dashboard while the second agent gets a warning in its context.

Running both installs at once

Nothing breaks. Claude Code runs every matching hook registration, so having the plugin and beacon init means each hook script is spawned two or three times per edit — but each event is handled exactly once. Every hook fingerprints the event it received and atomically claims it; whichever process gets there first does the work, and its siblings exit silently (src/dedupe.js). No duplicate rows, no duplicate warnings, no double-counted conflicts.

It is still wasted work, so Beacon tells you about it:

beacon doctor       # lists every place Beacon is registered, flags redundant ones
beacon uninit       # removes the settings.json hooks (use when moving to the plugin)

beacon init also detects an existing plugin install and stops rather than stacking on top of it (override with --force).

Global vs project scope

beacon init installs globally by default (~/.claude/settings.json), so every project is covered with one command. Prefer to scope it to a single repo? Use --project:

beacon init             # global — all projects (recommended default)
beacon init --project   # this repo only (.claude/settings.json)

The two levels are mutually exclusive — switching auto-disables the other. Running beacon init --project removes the global hook; running beacon init again removes the project hook. This guarantees the hook never fires twice for one edit. (It cleans the global level and the current project; if you'd enabled several projects individually, re-run --project in each to switch them off.) Global monitoring is safe: conflict detection is scoped by file path and working tree, so unrelated projects never raise false overlaps — global just means "always on, everywhere."

The daemon and dashboard are already machine-wide, so with global scope the dashboard becomes a single live view of everything you're doing across every repo.

How it works

   Claude Code session ──PreToolUse hook──┐
   Codex / MCP agent   ──MCP tools────────┤
   git / docker / CI   ──with_report──────┼──▶  beacon daemon  ──▶  live dashboard
   any editor / human  ──file watcher─────┘     (local HTTP, JSONL)     + in-context warnings

One idea, all the way down: an activity is { actor, action, target } — "session A is editing orders.ts". Everything is a client that reports activities; the daemon detects overlaps and answers "is anyone else on this?". That's it.

• Report and query are the only two operations. report even returns the conflicts in its response, so an agent learns of an overlap in the same call it announces its own work.

• Reporting is out-of-band (a hook / a shell wrapper), so your agent spends no tokens announcing itself.

• Awareness is surfaced only on a real conflict — a short, relevant line, exactly when it matters.

Integrations

Beacon is not locked to Claude Code. The core is a language-agnostic local HTTP bus; each integration is just a way to feed it activities.

Claude Code gets the richest experience because its hooks let Beacon both auto-report and inject the warning back into the agent mid-task. Every other tool still shows up on the dashboard and in everyone else's warnings.

Codex & other MCP clients

Beacon ships a zero-dependency MCP server, so any MCP-capable agent can report and query activity on the same bus your Claude Code sessions use.

Codex — install the plugin (recommended):

codex plugin marketplace add a1473838623/agent-beacon

Then install beacon from the plugin browser (codex /plugins). The plugin brings the hooks and the MCP server, exactly like the Claude Code one — same repo, same daemon.

Codex does not trust plugin hooks automatically. After installing, open the Hooks page (or run /hooks), review Beacon's three definitions and trust them — until you do, the hooks are inert and only the MCP tools work. Codex tracks trust by hash, so a Beacon release that changes the hook definitions needs trusting again.

Or wire just the MCP server, with no install at all:

# ~/.codex/config.toml
[mcp_servers.beacon]
command = "npx"
args = ["-y", "beacon-agents", "mcp"]

Or from the CLI, if you have beacon on your PATH:

beacon init --codex      # adds [mcp_servers.beacon] to ~/.codex/config.toml (global)

(Global by default; beacon init --codex --project scopes it to .codex/config.toml, and switching levels disables the other — same as the Claude hook.)

Either way, Codex reports to the same local daemon your Claude Code sessions use, so the two see each other. Installing Beacon as a plugin does not make it Claude-Code-only: the daemon is the bus, and the plugin just changes how the Claude Code side is wired to it.

Optionally add one line to your AGENTS.md so Codex uses it proactively:

Before editing a file or running a risky command, call the beacon get_activity / report_activity tools to avoid colliding with other agents.

Cursor / Cline / Windsurf / Zed / Claude Agent SDK: point the client's MCP config at the server. Zero-install: command: npx, args: ["-y", "beacon-agents", "mcp"]. If beacon is already on your PATH, beacon mcp works too.

What Codex gets with the plugin — measured in a live session:

• ✅ Warned before the edit. PreToolUse fires on apply_patch, and Beacon reports each file the patch touches. A real Codex session produced the matching pair in the activity log: active | editing | ...\work\codex-cli-hook-trigger.txt, then done when the turn ended.

• ✅ Same guards on destructive git, git add -A / commit -a, and redundant builds.

• ✅ Clears its presence when a turn ends, via the Stop hook — no stale rows.

• ✅ Visible to every other agent, on the dashboard and in everyone else's warnings.

Two things will make this look broken when it is not.

Restart Codex after installing. A session that was already running does not pick up newly installed hooks. Edit something in a session started before the install and nothing happens, in a way that looks exactly like the hooks not working.

The Hooks settings page does not list plugin hooks. It shows "no hooks found" even when they are installed and firing — the hooks OpenAI's own bundled plugins declare do not appear there either. Check beacon status or the dashboard instead: if a Codex session is reporting, the hooks are running.

Two implementation notes:

• Codex delivers a file edit as apply_patch with the whole patch in tool_input.command, not a path — and one call can touch several files. Beacon parses the patch envelope and reports each file, so a patch that collides on any one of them is caught (src/patch.js).

• Codex ignores a "hooks": "./hooks/hooks.json" string path in the manifest, even though the docs describe that form, and it does not expand ${CLAUDE_PLUGIN_ROOT} either, even though the docs list it as a compatibility alias — it passes the literal string through as a directory name. So the Codex manifest declares its hooks and its MCP server inline, the latter with a relative path and "cwd": "." rather than any variable, matching the only form OpenAI's own bundled plugins use. The same hooks are therefore declared twice, once per harness, and a test asserts the two copies stay in step.

Without the plugin — MCP-only — Codex is still visible to everyone and can call get_activity / report_activity, but nothing is injected automatically; the model has to choose to ask.

This section used to say Codex could not be warned before an edit. That was true of an earlier Codex, whose hooks fired only on Bash and could not add context. It is no longer the case.

Configuration

All optional — sensible defaults out of the box. Set as environment variables.

Troubleshooting & reporting bugs

Beacon fails open silently by design — so if something's off, the trail is in the local log, not your terminal.

beacon logs                 # last 200 lines + the log path
beacon logs --tail 50       # fewer lines
beacon logs --path          # just print the file path (~/.beacon/beacon.log)
beacon logs --clear         # wipe it

Errors and warnings (including every time the hook fails open because the daemon was unreachable) are always logged. For a full trace while reproducing a problem, restart with more detail:

BEACON_LOG_LEVEL=debug beacon start   # logs every report and tool call

Found a bug? Please open an issue and paste beacon logs output (review it first — it can contain file paths from your project). The log is 100% local; nothing is ever sent anywhere unless you attach it yourself.

FAQ

Will this slow my agents down or blow up my token usage? No. Reporting happens out-of-band (in the hook, not the model), so it costs zero model tokens. The only thing ever added to an agent's context is a single warning line, and only when there's a genuine overlap. No conflict → nothing added.

Can it break my workflow / block an edit? Not by default. It's advisory and fails open — daemon down, timeout, bad input, all result in "do nothing, allow." Set BEACON_GUARD=ask only if you want destructive git ops to pause for confirmation on a real conflict.

Does it send my code anywhere? No code, ever. Everything runs on 127.0.0.1 with settings and daily logs under ~/.beacon. The only network call Beacon can make is an update check against GitHub's public releases API — and only when you click Check for updates or opt into auto-check in Settings (both off by default). No telemetry, no accounts; your code and activity never leave your machine.

Does it replace git / locks / worktrees? No — it's the awareness layer underneath them. It doesn't take locks or move files; it makes agents see each other so they (or you) can coordinate. Pairs perfectly with git worktrees if you use them.

An activity is still showing after I stopped editing? It clears when your session's turn ends (a Stop hook) and otherwise fades a few minutes after the last edit. You can also hit Clear on the dashboard (with confirmation) to dismiss the board instantly — plus Restart / Quit the daemon right from the header (or beacon restart / beacon stop). Upgrading from an older version? Re-run beacon init to add the Stop hook, then beacon restart.

Is Clear destructive? No durable data is lost — Beacon never touches files, and the history log keeps every event. But it's global: it dismisses live presence for all sessions at once (active ones reappear on their next edit), so it's confirmed before it runs. Use it to wipe a board cluttered with stale entries.

Roadmap

• Native MCP server (report_activity / get_activity) — works with Codex, Cursor, Cline, Windsurf, Zed, and the Claude Agent SDK

• Codex plugin — hooks + MCP server, warned before every edit, same as Claude Code (0.10.0)

• SessionStart hook: greet each new session with a summary of what peers are doing

• Optional hard leases for resources that truly need serialization (e.g. one build at a time)

• Slack / desktop notification on overlap

• npx beacon-agents zero-install runner — done in 0.9.0

Ideas and PRs welcome — see CONTRIBUTING.md.

Contributing

Beacon is intentionally tiny (a few hundred lines, no dependencies). That makes it easy to read, easy to hack on, and easy to trust. Run the tests with npm test. Issues and pull requests are very welcome.

License

MIT © Beacon contributors