# Beacon

Beacon is the **visual planning surface for the coding agent in your terminal**.

You already have a Claude Code session running — that session is the brain. Beacon is its
**eyes and hands**: the place where the agent proposes a feature plan (roadmap features +
database schema + endpoints), you review it on a canvas instead of as a wall of text, give
scoped structured feedback, and approve or discard with a click. Beacon does **not** embed
a chatbot and does **not** generate plans on its own.

## How the loop closes

1. You ask the agent to plan a feature in your terminal session.
2. The agent calls the MCP tool `beacon_propose_plan`. The tool **blocks** waiting for your
   verdict.
3. Beacon renders the plan on `/plan` — a split screen with a native annotation panel on the
   left and the roadmap + database canvases tabbed on the right.
4. You review, annotate inline, optionally edit the `/map` and `/db` boards directly, then
   click **Submit feedback**, **Approve plan**, or **Discard**.
5. The verdict (plus any feedback) returns to the terminal session. On approve, the schema +
   roadmap drafts are persisted and the plan is archived to `/plan` history.

## Views

- **/plan** — the review surface: annotation panel + roadmap/database canvases + plan history.
- **/map** — the roadmap (features → sub-tasks → dependencies) and the architecture inventory,
  as interactive React Flow graphs. A **files** tab renders the live import graph.
- **/db** — the database design: tables (columns, PK/FK markers), FK relationships, and which
  endpoints touch which tables — with a distinct **draft** layer for proposed schema.
- **/settings** — intel model/provider/editor choices, code-map sync, and the danger zone.

## Stack

- Next.js 16 (App Router, React 19, Turbopack) · TypeScript · Tailwind v4
- ShadCN + **base-ui** primitives; React Flow (`@xyflow/react`) for the maps
- **Drizzle ORM** over **`bun:sqlite`** (Bun's built-in SQLite — no native addon, no driver
  adapter). The DB is local-only, one file per workspace under `~/.beacon/<id>/`.
- **Bun** for package management, runtime, and tests (`bun test` — native, no Vite)

## Install & run

Beacon ships as a CLI. Run it inside any repo:

```bash
beacon            # registers the repo, ensures the shared server, opens the panel
beacon doctor     # audit what's wired (global hooks, repo .mcp.json, AGENTS.md block)
beacon stop       # stop the shared background server
```

One shared Beacon server (daemon) serves every repo you open; each repo keeps its own data in
`~/.beacon/<id>/` (override the root with `BEACON_HOME`). On first run in a repo, run
`/beacon-init` in your Claude Code session to map the project's architecture, schema, and
roadmap into Beacon.

### Local development of Beacon itself

```bash
make install     # bun install
make dev         # next dev + the intel watcher together
make test        # bun test (data layer, mutations, ingest, plan loop, code graph, intel…)
make studio      # drizzle studio
```

> Schema note: edit `lib/drizzle/schema.ts`, then `bun run db:generate` (drizzle-kit) to add a
> migration and restart the dev server. Existing local DBs self-heal on open (lib/drizzle/provision).

## Live code-intelligence daemon (`intel/`)

As you write code (any language), a watcher keeps the `/db` and **files** maps in sync —
tables, FK relationships, endpoint↔table usage, and the import graph — updating live as you
save. It reads an optional `beacon.config.json` at the repo root (`roots[]`, `openapiUrl?`,
`controlUrl?`, `llm`), or derives everything from the repo when run via the CLI.

```bash
make up      # terminal 1: the panel server
make watch   # terminal 2: the watcher  (or `make dev` to run both)
```

On each save: debounced watcher → gather source files + the framework's OpenAPI spec + the
import graph → **the agent reads the code** and emits a structured graph (tables/columns/FKs +
endpoint↔table usage) → `POST /api/ingest` upserts it (preserving your manual nodes + hand-
placed positions) → SSE refreshes the open map. Introspected nodes show a green "live" dot.

**Provider — no API key needed.** `provider: "auto"` (default) runs extraction through the
**Claude Code CLI in headless mode** using your Claude Code subscription. Force it with
`"claude-cli"`, or set `"api"` + `ANTHROPIC_API_KEY` to use the Anthropic API instead. With
neither, the daemon still ingests endpoints from OpenAPI (deterministic-only).

## Deploy

Beacon is local-first: every user's boards live in per-workspace SQLite on their own machine,
so there is **no production database**. A hosted deployment is just the static app + (optionally)
read-only shared-board snapshots persisted to a blob/KV store — no Postgres, no migrations to run
against a server.
