beacon

Beacon

Turn any codebase, knowledge base, or docs into an interactive knowledge graph you can explore, search, and ask questions about.

---

You just joined a new team. The codebase is 200,000 lines of code. Where do you even start?

Beacon is a Claude Code Plugin that analyzes your project with a multi-agent pipeline, builds a knowledge graph of every file, function, class, and dependency, then gives you an interactive dashboard to explore it all visually. Stop reading code blind. Start seeing the big picture.

The goal isn't a graph that wows you with how complex your codebase is — it's a graph that quietly teaches you how every piece fits together.

---

✨ Features

Explore the structural graph

Navigate your codebase as an interactive knowledge graph — every file, function, and class is a node you can click, search, and explore. Select any node to see plain-English summaries, relationships, and guided tours.

Understand business logic

Switch to the domain view and see how your code maps to real business processes — domains, flows, and steps laid out as a horizontal graph.

Analyze knowledge bases

Point /beacon-knowledge at a Karpathy-pattern LLM wiki and get a force-directed knowledge graph with community clustering. The deterministic parser extracts wikilinks and categories from index.md, then LLM agents discover implicit relationships, extract entities, and surface claims — turning your wiki into a navigable graph of interconnected ideas.

🧭 Guided Tours Auto-generated walkthroughs of the architecture, ordered by dependency. Learn the codebase in the right order.	🔍 Fuzzy & Semantic Search Find anything by name or by meaning. Search "which parts handle auth?" and get relevant results across the graph.
📊 Diff Impact Analysis See which parts of the system your changes affect before you commit. Understand ripple effects across the codebase.	🎭 Persona-Adaptive UI The dashboard adjusts its detail level based on who you are — junior dev, PM, or power user.
🏗️ Layer Visualization Automatic grouping by architectural layer — API, Service, Data, UI, Utility — with color-coded legend.	📚 Language Concepts 12 programming patterns (generics, closures, decorators, etc.) explained in context wherever they appear.

---

🚀 Quick Start

1. Install the plugin

/plugin marketplace add jawhnycooke/beacon
/plugin install beacon

2. Analyze your codebase

/beacon

A multi-agent pipeline scans your project, extracts every file, function, class, and dependency, then builds a knowledge graph saved to .beacon/knowledge-graph.json.

3. Explore the dashboard

/beacon-dashboard

An interactive web dashboard opens with your codebase visualized as a graph — color-coded by architectural layer, searchable, and clickable. Select any node to see its code, relationships, and a plain-English explanation.

4. Keep learning

# Ask anything about the codebase
/beacon-chat How does the payment flow work?

# Analyze impact of your current changes
/beacon-diff

# Deep-dive into a specific file or function
/beacon-explain src/auth/login.ts

# Generate an onboarding guide for new team members
/beacon-onboard

# Extract business domain knowledge (domains, flows, steps)
/beacon-domain

# Analyze a Karpathy-pattern LLM wiki knowledge base
/beacon-knowledge ~/path/to/wiki

---

📦 Share the Graph with Your Team

The graph is just JSON — commit it once, and teammates skip the pipeline. Good for onboarding, PR reviews, and docs-as-code.

What to commit: everything in .beacon/ except intermediate/ and diff-overlay.json (those are local scratch).

.beacon/intermediate/
.beacon/diff-overlay.json

Keep it fresh: enable /beacon --auto-update — a post-commit hook incrementally patches the graph so each commit lands with a matching graph. Or re-run /beacon manually before releases.

Large graphs (10 MB+): track with git-lfs.

git lfs install
git lfs track ".beacon/*.json"
git add .gitattributes .beacon/

---

🔧 Under the Hood

Multi-Agent Pipeline

The /beacon command orchestrates 5 specialized agents, and /beacon-domain adds a 6th: