Beacon docs

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, no account, no API key. 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. 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. 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. 3

   Ask the agent to plan a feature. It calls beacon_propose_plan and the plan renders live on /plan.

4. 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:

1. Propose. The agent calls beacon_propose_plan (or you present a plan in plan mode). The tool blocks — the session waits for your verdict.

2. 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.

3. Decide. Approve, Discard, or Submit feedback. Feedback bundles your inline notes plus any board edits.

4. Return. The verdict flows back to the terminal. On feedback, the agent revises and re-proposes — the loop continues.

5. 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`

Register the current repo, ensure the shared server is running, and open the panel on this repo. The everyday command.

`$ 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.

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.

Notes

No notes yet. Hit + to start one.

Select a note, or create one. Then @-mention it in your terminal to turn it into features.