How to use Beacon

Skills — type these in your terminal session

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

• /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 this 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 already produced — adds new components, drops removed ones, picks up new tables and routes. Anything you added by hand on the canvas survives the refresh.

MCP tools — the agent calls these on its own

You don't run these. The agent reaches for them whenever they fit the task — knowing they exist helps you understand what the agent is doing.

• beacon_context_for_feature
  Before touching code for a feature, the agent uses this to pull the files attached to it 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 uses this on a file it's about to edit to see what imports it and what it imports — so it can judge whether the change is safe.
• beacon_propose_plan
  When the agent has a feature plan (tables + relations + endpoints), this opens the plan on Beacon's /plan page and BLOCKS the session. You review, annotate, then Approve / Discard / Submit feedback — and the agent only continues after you've decided.
• beacon_describe_feature
  When a feature is done, the agent calls this with a short markdown summary and the files it touched. That keeps the next session's beacon_context_for_feature accurate.
• beacon_entities
  Generic readout of what's currently mapped — features, architecture, tables, endpoints. The agent uses it when it just needs raw planning data.
• beacon_map
  Quick list of features on the roadmap. The agent calls this near the start of work to see what's already planned.
• beacon_start_feature
  Optional: the agent flags which feature it's working on. The /map view shows it as in-progress while edits happen.
• beacon_add_subtasks
  Breaks a feature into smaller child nodes on the /map view. Useful when one feature naturally splits into several pieces.
• beacon_init_persist
  The write side of /beacon-init and /beacon-refresh — you never call it directly; the skills do.

Automatic hooks — these run without you

Wired into Claude Code globally. You don't trigger them; 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 agent's next instruction. No prompt walls of text in the terminal.
• File edits (PostToolUse)
  Every Edit/Write/MultiEdit the agent runs is reported to Beacon, and the file is automatically attached to whichever feature the session is currently working on. The /map view gradually fills in with the real files behind each feature, without you tagging anything.
• Inline code-graph watcher
  While the panel is open, a background watcher rebuilds the /map → Files view as you save code. No clicking required — it just stays current with the repo it's watching.

Typical loop, end to end

1. First time in a repo: run beacon in the terminal, then /beacon-init in your session.
2. Ask the agent to plan a feature. It calls beacon_propose_plan; you review on /plan; you Approve.
3. The agent implements. File edits land on the canvas automatically via the PostToolUse hook.
4. When done, the agent calls beacon_describe_feature so the next session has accurate context.
5. Every few weeks, run /beacon-refresh to keep the architecture map honest as the code grows.