Docs — Beacon

Overview

What is Beacon

Beacon is the visual planning surface for the coding agent in your terminal. That session is the brain; Beacon is its eyes and hands. The agent proposes a feature plan — roadmap features, database schema, and endpoints — you review it on a canvas instead of a wall of text, give scoped feedback, and approve or discard with a click. The verdict flows straight back to your session.

It runs entirely on your machine — local-first, your code never leaves it. One shared server quietly serves every repo you open; each keeps its own data under ~/.beacon.

Get started

Install

One command. It installs Bun if you don't have it, then puts the beacon CLI on your PATH. Re-run it any time to update.

$curl -fsSL https://www.trybeacon.sh/install.sh | sh

Then, inside any repository:

$beacon

Get started

Quickstart

1
Install with the command above, then run beacon inside a repo. It registers the repo, starts the shared server, and opens the panel in your browser.
2
In your Claude Code session, run /beacon-init. The agent reads the repo and draws its architecture, schema, and roadmap onto the canvas.
3
Ask the agent to plan a feature. It calls beacon_propose_plan and the plan renders live on /plan.
4
Review it — annotate inline, edit the boards — then Approve, Submit feedback, or Discard. Your verdict returns to the session.

Concepts

The planning loop

The loop is the whole point. It closes in five steps:

Propose. The agent calls beacon_propose_plan (or you present a plan in plan mode). The tool blocks — the session waits for your verdict.
Review. The plan renders on /plan: a native annotation panel on the left, the roadmap and database boards on the right. Select text to comment; edit the boards directly.
Decide. Approve, Discard, or Submit feedback. Feedback bundles your inline notes plus any board edits.
Return. The verdict flows back to the terminal. On feedback, the agent revises and re-proposes — the loop continues.
Record. On approval the schema and roadmap drafts persist, and when the work is done the agent calls beacon_describe_feature so the next session has accurate context.

Concepts

The canvases

/map

The roadmap: feature cards, their sub-tasks, and dependency links — plus a separate architecture view of the real components. Files the agent edits attach themselves here.

/db

The database design board: tables and columns, endpoints, and the endpoint→table links. Proposed schema lands as a distinct draft layer you can approve or discard.

/plan

The split-screen review page: annotations on the left, the roadmap + database boards tabbed on the right, plus a history of every plan and its verdict.

Reference

CLI reference

$ beacon

$ beacon doctor

Audit what's wired — the global Claude Code hooks + skills, this repo's .mcp.json, and the running daemon.

$ beacon stop

Stop the shared background server. It restarts the next time you run beacon.

$ beacon setup

(Re)install Beacon's per-repo helpers — the skills and .mcp.json — in the current repo without opening the panel.

$ beacon uninstall

Reverse every Beacon artifact: the global ~/.claude wiring and the per-repo files.

$ beacon mcp

The stdio MCP server Claude Code spawns automatically. You never run this by hand.

Reference

Claude Code integration

Skills — you type these

Slash commands that tell the agent to do something Beacon-shaped.

/beacon-init

When: First time you point Beacon at a repo. The agent reads the codebase and fills Beacon's map — the main components, the rough roadmap themes, the database schema, and the endpoints. Run it once per repo to bootstrap the picture.

/beacon-refresh

When: Every few weeks, or after a big set of changes. The agent re-surveys the repo and updates what /beacon-init produced — adds new components, drops removed ones, picks up new tables and routes. Anything you added by hand on the canvas survives.

/beacon-plan

When: Whenever you want to review an approach on the canvas. Present the current plan or approach on Beacon's /plan page for annotation instead of asking for approval as a wall of text.

MCP tools — the agent calls these

You don't run these; the agent reaches for them when they fit. Knowing they exist makes its moves legible.

beacon_context_for_feature

Before touching code, the agent pulls the files attached to a feature plus their imports, the endpoints in that domain, the tables those endpoints touch, and the surrounding components — one round-trip instead of a blind Glob/Grep scan.

beacon_blast_radius

Mid-feature, the agent runs this on a file it's about to edit to see what imports it and what it imports — so it can judge whether a change is safe.

beacon_propose_plan

When the agent has a feature plan (tables + relations + endpoints), this opens it on /plan and BLOCKS the session until you Approve, Discard, or Submit feedback.

beacon_describe_feature

When a feature is done, the agent records a short markdown summary and the files it touched, keeping the next session's context accurate.

beacon_map

A quick list of features already on the roadmap. The agent calls it near the start of work to avoid duplicating what's planned.

beacon_entities

A raw readout of everything mapped — features, architecture, tables, endpoints — when the agent just needs the planning data.

Hooks — these run on their own

Wired into Claude Code globally; they react to what the session is already doing.

Plan mode (ExitPlanMode)

When the agent shows you a plan, Beacon intercepts it and renders the markdown on /plan with a native annotation panel. Select text and type → it becomes a comment. Approve / Discard / Submit feedback flows back to the session as the next instruction.

File edits (PostToolUse)

Every Edit/Write the agent runs is reported to Beacon and the file is attached to whichever feature the session is working on. The /map view fills in with the real files behind each feature, without you tagging anything.

Code-graph watcher

While the panel is open, a background watcher rebuilds the Files view as you save code — the maps stay current with the repo on their own.

Reference

Configuration

BEACON_HOME

Where per-workspace data lives — the SQLite databases and the server record. Defaults to ~/.beacon.

PORT

Port for the shared local server. Defaults to 4319.

Settings → intel

In the panel, the Settings page drives the code-intelligence model/provider and your editor, and triggers a code-map sync.

Reference

Telemetry

Beacon sends an anonymous heartbeat at most every 12 hours while the local server runs, so we can count active installs (npm download numbers are dominated by mirrors and CI). The payload is exactly five fields — verify it yourself anytime with beacon telemetry status, which prints the exact payload that gets sent.

What is sent

A random machine id (a UUID generated locally — tied to nothing), the Beacon version, the operating system (darwin/linux/win32), the CPU architecture, and whether the machine is a CI runner.

What is never sent

Repo names, file paths, code, plans, board content, environment variables, or anything derived from them. IP addresses are not stored.

Opting out

Any of: beacon telemetry off, the env var BEACON_TELEMETRY_DISABLED=1, or the cross-tool DO_NOT_TRACK=1 convention. Re-enable with beacon telemetry on.

Help

Troubleshooting

When something looks off, start here:

$beacon doctor

The panel won't open

Make sure the server is up — run beacon again, or beacon stop then beacon to restart it.

The @beacon tools or skills are missing in Claude Code

Run beacon setup in the repo, then restart your Claude Code session so it re-reads the MCP registration.

How do I update?

Re-run the install command — it fetches the latest and relinks. Nothing else to do.