Beacon

Navigate open source like you've been there before.

Paste a GitHub repo URL. Beacon's AI agent explores it — reading issues, PRs, contributors, and code — then returns ranked contribution opportunities, an architecture breakdown, a health snapshot, and the best files to start with. Then ask it anything about the repo.

---

What you get

Feed	Every repo you track with its top AI-ranked issues — searchable, sortable, filterable by language, fully keyboard-driven
Repo report	Ranked issues (score, difficulty, freshness signals), architecture + ownership map, health snapshot, "start here" reading list
Issue deep research	One click on any issue: concrete approach, files to touch, similar merged PRs, effort estimate, reviewer to ping
Repo chat	Streamed Q&A grounded in the stored analysis — with suggested follow-ups and per-session history
Find my issue	Tell Beacon your skills and level; it ranks every open pick across all tracked repos by fit
Bookmarks & export	Star issues into a shortlist, export any report as Markdown, share report links

Everything the agent does streams live to the UI over WebSocket — you watch it read the repo.

Quick start

cp .env.example .env
# Add your OPENROUTER_API_KEY
docker compose up --build

Open http://localhost:5173

How it works

Paste repo URL  →  AI agent explores GitHub iteratively (tool-calling loop)
                →  Issues, PRs, contributors, file tree, files on demand
                →  Structured analysis validated against JSON Schema
                →  Streamed live to the UI · cached 24h · chat on top

Built to stay cheap: compact prompts, capped tool outputs, a per-run token budget, a cheap-first model fallback chain, and aggressive caching (24h analyses, 7-day issue research, dedup of concurrent runs). Chat never re-fetches GitHub — it's grounded in the stored analysis, one completion per message.

Deep dives:

• docs/ARCHITECTURE.md — system design, agent loop, data model, cost controls
• docs/API.md — every route, SSE chat stream, WebSocket events
• ROADMAP.md — what's shipped and what's next

Keyboard shortcuts

Key	Action
⌘K / Ctrl-K	Command palette — jump to any repo or action
/	Focus feed search
j / k	Move through the feed
↵	Open highlighted repo
r	Deep-research the highlighted repo's top issue
Esc	Close drawer / palette

Local dev

make dev-db          # Postgres only
make dev-backend     # backend with hot reload
make dev-frontend    # Vite dev server
make test            # run all tests
make coverage        # run tests with coverage report

Environment variables

Variable	Required	Description
OPENROUTER_API_KEY	✓	OpenRouter API key
GITHUB_TOKEN	—	Increases GitHub rate limits (60 → 5000 req/hr)
OPENROUTER_MODEL	—	Primary model (default openai/gpt-4o-mini)
OPENROUTER_MODEL_FALLBACKS	—	Comma-separated fallback models tried on provider errors
AGENT_TOKEN_BUDGET	—	Max total tokens per agent run (default 150000)
RATE_LIMIT_PER_MIN	—	Per-IP requests/min on mutating routes (default 20)