Open-source, bring-your-own-key monitoring for how your brand shows up in AI assistant answers.
Track topics · auto-generate the questions people actually ask AI · watch trends over time · benchmark competitors' share of voice.
Lettertrace is a self-hostable AEO tool, focused purely on diagnosing and monitoring AI mentions (a.k.a. Answer Engine Optimization / Generative Engine Optimization). You describe your brand and a few topics; Lettertrace generates realistic prompts a person might ask ChatGPT or Claude, runs them against those models with your own API key, detects when your brand and your competitors get mentioned, and charts how your visibility, sentiment, and share of voice move over time.
- 🔓 Open source (MIT) and BYOK, you bring your own Anthropic / OpenAI / Google / Perplexity keys — or a single LLM router key (Concentrate) instead. Either way they're encrypted at rest and never leave your infrastructure.
- 🧠 Multi-model, query Claude (Anthropic), ChatGPT (OpenAI), Gemini and Google AI Overviews (both on your Google key), and Perplexity Sonar. Add more providers easily.
- 🧩 Topics → variations, auto-generate the different questions people ask AI about each topic.
- 📈 Trends over time, visibility, share of voice, prominence, and sentiment across runs.
- ⚔️ Competitor benchmarking, ingest competitors and see how often each shows up.
- 🏢 Multiple organizations, one account can track many brands/domains and switch between them from the sidebar.
- 🔎 Web search + source attribution, query the models with their native web search on and capture the exact sources they cite, so you can see which posts drove an answer, and whether your own site is being used, even when you aren't named.
- ⏱️ Scheduled monitoring, daily/weekly/custom-interval runs via a cron endpoint.
Core concepts
| Concept | What it is |
|---|
| Organization (project) | A brand's workspace: brand name, aliases, domain, default model, schedule. An account can have several, the sidebar selector switches the whole dashboard between them, and ＋ New organization re-opens the setup wizard. |
| Team | An organization can have more than one person on it. The owner created it and pays for its runs; members are invited by email and work alongside them. See Teams. |
| Competitors | Brands you benchmark against (name + aliases). |
| Topics | Subjects you want to monitor (e.g. "project management software"). |
| Prompts (variations) | Natural questions generated for a topic, the queries actually sent to the model. |
| Runs | One execution: every active prompt → the model → detect mentions → store. |
| Mentions | A detected reference to your brand/competitor in an answer, with count, prominence, sentiment, and whether it was recommended. |
How mention detection works
For each answer the model returns, Lettertrace:
- Deterministic detection, matches your brand's and each competitor's name + aliases (word-boundary, case-insensitive), recording occurrence count and first position (prominence).
- LLM enrichment, for the entities that were mentioned, a structured call classifies sentiment and whether the answer recommended them.
- Aggregation, visibility (mention rate), share of voice, average prominence, and sentiment are computed per run and trended over time.
Tech stack
- Next.js 14 (App Router, TypeScript) · Tailwind CSS · Recharts
- Supabase, Postgres, Auth, and Row Level Security
- BYOK provider keys encrypted with AES-256-GCM at rest
- Anthropic (
@anthropic-ai/sdk) + OpenAI (openai) SDK adapters, plus dependency-free REST adapters for Google Gemini (Gemini models + Google AI Overviews, via Google Search grounding) and Perplexity Sonar (always search-grounded, real source URLs)
Getting started
1. Create a Supabase project
At supabase.com, create a project. From Settings → API grab:
Project URL → NEXT_PUBLIC_SUPABASE_URLanon public key → NEXT_PUBLIC_SUPABASE_ANON_KEYservice_role key → SUPABASE_SERVICE_ROLE_KEY (only needed for scheduled runs)
2. Apply the database schema
Open the Supabase SQL Editor and run the contents of supabase/schema.sql. It creates all tables, indexes, Row Level Security policies, and a trigger that auto-creates a profile on sign-up. It's safe to re-run.
Email confirmation: for the smoothest local experience, disable "Confirm email" under Authentication → Providers → Email, or confirm via the link (handled by /auth/callback).
Social sign-in (optional)
The sign-in screen offers Google and GitHub alongside email + password. Both are optional — if a provider isn't enabled in Supabase, its button will simply error when clicked, so remove it from oauthProviders in app/login/auth-form.tsx if you don't plan to configure it.
No new environment variables are involved: the client secrets live in Supabase, not in this repo.
1. Register the app with each provider. Both point at Supabase's callback, not yours — which means one registration covers local development and production:
https://<project-ref>.supabase.co/auth/v1/callback
- GitHub → Settings → Developer settings → OAuth Apps → New OAuth App. Leave "Enable Device Flow" unchecked.
- Google → Cloud Console → APIs & Services → Credentials → OAuth client ID (Web application). Add
https://<project-ref>.supabase.co as an authorized JavaScript origin. On the consent screen, request only the default non-sensitive scopes (email, profile, openid) — those need no verification review, but the app must be published to In production to accept more than 100 users, and any domain in your consent-screen links must be verified in Search Console.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
