Brave Goggles: A DSL for Rewriting Search Results in Real-Time

Hook

What if you could tell Google to never show you content from specific domains, or permanently boost academic papers over blog posts? Brave built exactly that—and made it open source.

Context

Every search engine makes editorial decisions. Google's PageRank prioritizes link popularity. DuckDuckGo emphasizes privacy but still ranks results using proprietary algorithms. These black-box systems work well for general queries but fail specialized use cases: researchers need academic sources surfaced first, developers want documentation prioritized over tutorials, journalists need recent sources from credible outlets. The fundamental problem is that a single ranking algorithm cannot serve infinite use cases.

Brave Search Goggles addresses this through user-controlled re-ranking. Instead of accepting the search engine's default ordering, users write text files containing rules that filter and boost results based on URL patterns, domains, or content characteristics. These 'Goggles' transform search results transparently and algorithmically, creating unlimited custom search experiences without requiring users to trust yet another proprietary ranking system. The brave/goggles-quickstart repository teaches this system through examples and documentation, democratizing search result curation beyond the handful of engineers at major tech companies.

Technical Insight

Goggles files use a domain-specific language (DSL) that reads like configuration but executes as a series of transformations against search result sets. The syntax centers on pattern matching with actions. A simple Goggle might look like:

! name: Academic Research Prioritization
! description: Boost scholarly sources, demote commercial content
! public: true
! author: researcher@university.edu

$boost=2,site=*.edu
$boost=3,site=arxiv.org|scholar.google.com
$downrank=1,site=*.com
$discard,site=pinterest.com|quora.com

Each instruction begins with a directive ($boost, $downrank, $discard) followed by a magnitude and pattern-matching criteria. The $boost=2 multiplies relevance scores, while $discard removes results entirely. Patterns support wildcards, pipe-delimited alternatives, and domain hierarchies. The engine processes these sequentially, applying transformations to Brave's result set.

The architecture separates concerns cleanly. Brave's core search index remains untouched—Goggles operate as a post-processing layer. When you append &goggles_id=<url> to a search query, Brave fetches the Goggle file, parses it into an abstract syntax tree, and applies transformations before rendering results. This means Goggles work on existing rankings, not raw documents, which has profound implications: you cannot boost content that Brave's crawler never indexed, and heavily downranked results still count against the result set size.

More sophisticated Goggles leverage conditional logic and composite patterns:

! name: Developer Documentation Focus

$boost=5,site=docs.python.org|go.dev/doc|nodejs.org/docs
$boost=2,inurl:documentation|/docs/|/guide/
$downrank=2,site=medium.com,inurl:/tutorials/
$discard,site=w3schools.com
$discard,inurl:?utm_source=|/amp/

The inurl: matcher scans URL paths for patterns—useful for prioritizing official documentation paths over blog tutorials. Composite conditions like site=medium.com,inurl:/tutorials/ create AND logic: both conditions must match. This granularity allows precise targeting: you might boost Stack Overflow for error messages but downrank it for conceptual questions.

Goggles compile to a lightweight execution format. The parser validates syntax, expands wildcards into efficient data structures (likely tries or hash tables for domain matching), and creates a ranking modifier function. When Brave retrieves search results, it iterates through each result URL, tests it against Goggle patterns, and accumulates score adjustments. The modified scores get re-sorted before display. This client-side execution model preserves privacy—your Goggle preference doesn't require sending personalized ranking signals to Brave's servers.

The system's power emerges through composition of simple rules. A news-focused Goggle might combine recency signals with source credibility:

$boost=3,site=apnews.com|reuters.com|propublica.org
$boost=1,site=*.gov
$downrank=3,site=dailymail.co.uk|nypost.com
$discard,inurl:opinion|/editorial/|/commentary/

This creates an editorially transparent search experience. Unlike algorithmic adjustments buried in proprietary ranking systems, these rules are readable, auditable, and forkable. Communities can share Goggles, debate their merits, and iterate on shared search perspectives.

Gotcha

Goggles suffer from fundamental architectural constraints. You're re-ranking Brave's existing index, not expanding it. If critical content isn't in Brave's crawl, no amount of boosting surfaces it. Researchers seeking niche academic papers or developers looking for fresh documentation might find their carefully crafted Goggles ineffective if Brave hasn't indexed those sources. The system cannot compensate for index coverage gaps—a significant limitation compared to Google Custom Search, which lets you specify indexing targets.

The single-Goggle restriction creates UX friction. You cannot stack a "boost academic sources" Goggle with a "filter out paywalls" Goggle. Each search applies exactly one perspective. This prevents modular composition—the ability to layer concerns like Unix pipes. If you want both academic prioritization and paywall filtering, you must manually merge rules into a single file, creating maintenance burden as your needs evolve. The lack of Goggle composition also prevents community specialization: one person might curate credible news sources while another maintains paywall filters, but users cannot combine their work. This monolithic approach limits the marketplace-of-ideas potential that Brave touts.

Verdict

Use if: You have recurring, specialized search needs that mainstream engines handle poorly—academic research requiring scholarly sources, technical work needing official documentation over blog spam, or news consumption demanding source credibility filters. Goggles excel when you've identified specific domains or URL patterns that consistently improve your results, and you're willing to invest 30 minutes learning the DSL syntax for long-term search quality gains. They're particularly valuable for communities that can share and iterate on Goggles collaboratively, creating shared search perspectives with transparent ranking rules. Skip if: You need general-purpose search without customization, require results from sources outside Brave's index coverage, want to combine multiple ranking perspectives simultaneously, or primarily search on mobile where switching Goggles creates friction. The system's value is proportional to how repetitive and specialized your search patterns are—casual users gain little, but domain experts can dramatically improve signal-to-noise ratios.