# brave goggles-quickstart: how Goggles re-rank Brave Search > Goggles are a set of instructions, rules and filters, that anyone can write and apply to re-rank Brave Search results for themselves or for a community. The goggles-quickstart repository is the educational content for that, a syntax guide, a lifecycle guide, and a FAQ that answers the awkward questions about ownership, polarisation, and the fact that one Goggle can be used at a time. **brave/goggles-quickstart** — Educational material to learn about Goggles and how to create your own. - Repository: https://github.com/brave/goggles-quickstart - Website: https://search.brave.com/goggles - Stars: 775 · Forks: 97 - Language: Unknown - License: not declared - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/brave-goggles-quickstart ## One index, many rankings Goggles enable anyone, be it an individual or a community, to alter the ranking of Brave Search by using a set of instructions, which the project calls rules and filters. Anyone can create, apply, or extend a Goggle, and the summary the README gives is that essentially Goggles act as a custom re-ranking on top of Brave's search index. That framing is the whole design. There is one index, the web, and one ranking engine, and the Goggle is a layer that reshapes the ordering of the results that engine returns. It is not a separate crawler, not a separate corpus, and not a search engine you run yourself. That distinction is what makes Goggles cheap to create and easy to share, and it is also what makes the interesting questions about them questions about ranking rather than about infrastructure. The motivation is stated carefully, and it is worth reading closely because it is more measured than the phrase custom search usually attracts. Brave Search does not have editorial biases, but all search engines have some level of intrinsic bias due to underlying data, meaning the web, and some algorithmic choices of features to select. Goggles allows users to counter such intrinsic biases in the ranking, and also to create custom search experiences that could not be covered by an all-purpose search engine such as Brave Search. So there are two distinct uses here, and they pull in different directions. Countering bias is a corrective act, a way of making an existing ranking less distorted by the shape of the web. Creating a custom search experience is a creative act, a way of building a small specialised tool on top of a general index. The same mechanism does both, and the FAQ in this repository deals with the uncomfortable consequences of that, which is a good sign about how seriously the project takes the idea. The repository itself is educational content rather than software. Its contents are a README, a getting-started guide, a FAQ, a directory of Goggle files, some assets, and a contributing guide. ## Create, apply, extend, own Four verbs describe the whole lifecycle, and the README states each of them in one sentence. Create. Anyone can create a Goggle, and the FAQ has an entry asking whether that is only for developers, which suggests the question comes up often. The answer implied by the rest of the material is that a Goggle is a text file of instructions, and that the quickstart guide in the goggles directory is the starting point for writing one. Apply. A Goggle is applied by passing its URL together with a query, so a Goggle is something you point at rather than something you install. That is a deliberate privacy property, and the README explains it later. Extend. The README says anyone can fork or extend existing Goggles, and the getting started guide has sections for updating a Goggle, for fine-tuning one, and for sharing a Goggle with the world. So the ecosystem is intended to be cumulative, with community Goggles building on each other. Own. Goggles are owned solely by their creators, and if a Goggle is public it can be used by anyone on top of the Brave Search index. The FAQ expands on this with two questions, who owns a Goggle, and can Goggles ownership be transferred, so the answer to the second one is clearly not automatic. The three destinations for a Goggle are therefore distinct. You can keep one private and use it yourself, you can publish it so anyone can apply it, or you can fork someone else's and make it your own. The difference matters for the privacy question, because a Goggle that only you use is a different artefact from one that thousands of people apply. The main entry point for someone writing their own is the Goggles quickstart guide, which lives in the repository at the path goggles/quickstart.goggle, and the longer background is the Goggles whitepaper on brave.com. ## The guide is organised around the lifecycle The getting started document is indexed in the README, and the section names tell you what the guide actually teaches. It starts with Goggles syntax, which is the vocabulary of the instruction language, and then walks the lifecycle: creating a Goggle, updating a Goggle, and deleting a Goggle. After that comes learn by example, fine-tuning a Goggle, and sharing a Goggle with the world. Then there are the two sections that make this guide worth reading, because they are the questions every implementer of a ranking layer has to answer. The first is what happens when two instructions are conflicting. If a Goggle is a set of rules and filters, and two of them point in opposite directions, the behaviour has to be defined rather than left to the implementation. A guide that documents the conflict resolution is a guide written by people who have hit the ambiguity, and it means you can write a Goggle without reading the search engine's internals to find out what wins. The second is how to exclude any result not matched by the Goggle. That is the inverse operation, and it is the one that turns a Goggle from a re-ranking into a filter, which is a different and more powerful thing than changing the order of results. If you can say what must be present, you can build a search over a subset of the web without having to build a corpus. For a reader evaluating the project, the presence of these two sections is more informative than any feature list would be. A ranking system that only ever reorders is a preference. One that can exclude is a filter, and filters are the thing that turns a general index into something a community can actually use, whether that community is a research group or a language community or a hobby. ## The FAQ asks the awkward questions first The FAQ document is indexed in the README, and the order of the questions is revealing. The first two are about ownership and about limits. Who owns a Goggle, and why can't I apply multiple Goggles at the same time. The second of those is a hard product limit and it is the one that most affects how you design a workflow around Goggles. If your users need one ranking for research and another for personal browsing, they cannot have both at once, and the choice has to be made per query. Then the questions that get at the social side. Can Goggles ownership be transferred, and do Goggles contribute to polarization. The polarisation question is the one that a project shipping ranking overrides cannot dodge, because a Goggle is a rule set that can encode a viewpoint, and a community of like-minded users applying one to the same web is a feedback loop. A document that lists the question in its table of contents, rather than burying it, is at least acknowledging the design surface it has created, and the README's own framing, that Goggles exist partly to counter intrinsic bias in a general ranking, is the argument it makes about why the feature is worth having. The rest of the FAQ covers the practical edges. Why is a particular page not recoverable with Goggles, which is a question about pages that the index has but that a Goggle's rules exclude. Can anyone create a Goggle or is it only for developers. How can I discover new Goggles, which the README points at the discover page on the search site for. And there is a what's next for Goggles entry, which is the one to read if you want to know where the project is going. ## A Goggle URL can become an identifier The privacy section is short and it is the most technically interesting paragraph in the repository, so it deserves to be read twice. To apply a Goggle, a user needs to pass the Goggle URL together with a query. Brave treats Goggle URLs with the same strict provisions it uses for other data elements, like IP addresses or geo-coordinates, that could serve as identifiers. Brave does not track the queries of any of its users, and searching with Goggles is no exception. But then the caveat arrives, and it is a real one. If a Goggle is used only by one person, or by a very small number of people, the Goggle URL could serve as an identifier, and enable the creation of a profile of that user's queries while using that particular Goggle. So the privacy protection is not absolute, and the reason is structural rather than a policy failure. A URL that identifies a config object becomes sensitive when few people use it, because a rare identifier plus a history of queries is a profile. The same logic applies to a private Goggle that only your team applies, and it is the reason the FAQ asks how Goggle ownership can be transferred, since moving a Goggle to a new owner changes who the URL points at and therefore what it identifies. The practical consequence for an organisation that wants to standardise on a Goggle is that it has to be popular enough not to be identifying, which sounds perverse but follows directly from the stated reasoning. A Goggle with thousands of users is anonymous, a Goggle with five users is a fingerprint. For the same reason, a team that wants to use a Goggle internally should think about whether a private, low adoption Goggle is a good idea, and the answer the privacy section gives is that it is a weaker position than it looks. ## A documentation repository, with a directory of Goggles It is worth being clear about what this repository is, because the name, goggles-quickstart, sounds like a starter template and it is not. The top level holds a README, the getting started guide, the FAQ, a CONTRIBUTING.md, an assets directory, and a goggles directory. The goggles directory is where the quickstart Goggle lives, at the path goggles/quickstart.goggle, and it is the file the README points to when it says you want to start building your own or fork or extend existing ones. So the deliverable is a set of documents plus one worked example, and the project asks for contributions to it, which is the normal shape for a specification that a wider community is meant to write against. The wider context is on the Brave site rather than in the repository. There is a Try it page, a Discover page for finding public Goggles, and a whitepaper that covers the motivation, which the README points to when it says to check it out if you want to learn more about the motivation for Goggles. The repository topics are ranking, search, and transparency, and the homepage for the project is the search.brave.com goggles page. On maintenance, the repository is not archived, the last push was on 2026-04-22, and there are no GitHub releases, which is consistent with a set of documents that evolves when the format or the product changes rather than on a version schedule. The licence is not classified by GitHub, and the primary language is not recorded either, since the content is prose and configuration rather than code. For an engineer, the practical sequence is short: read the syntax section, copy the quickstart Goggle, change one rule, apply it, and read the two sections about conflicting instructions and about excluding results. That is the fastest way to understand what Goggles can and cannot express. ## Conclusion goggles-quickstart fits a person or a community that wants a different ranking from Brave Search, whether to counter the intrinsic bias of a general web index, to exclude certain sources, or to build a search experience for a specialised corpus. It does not fit a user who wants to layer several rankings at once, since the FAQ states that only one Goggle can be applied at a time, and it does not fit an organisation that needs its members to adopt a shared Goggle without them being individually identified by the Goggle URL. Verify first that the Goggle you want to publish is something you own and can maintain, that the instructions you write do not conflict with each other, since the guide has a section on exactly that, and that you have read the privacy section, because a Goggle used by only a handful of people can become an identifier for the queries of those people. ## FAQ ### What are Goggles in Brave Search? They are a set of instructions, rules and filters, that anyone can create, apply or extend, and that act as a custom re-ranking on top of the Brave Search index. A Goggle is owned by its creator, and a public one can be applied by anyone. ### Can I apply more than one Goggle at a time? No. The FAQ in the repository lists why you cannot apply multiple Goggles at the same time as a question of its own, so a user has to choose one ranking per query rather than layering them. ### What is the privacy risk of a Goggle URL? Brave treats Goggle URLs with the same strict provisions as other identifiers such as IP addresses and geo-coordinates, and does not track queries. But the README notes that if a Goggle is used by only one person or a very small number of people, the URL could serve as an identifier and enable a profile of that user's queries. ### How do I start writing my own Goggle? The repository points to the Goggles quickstart guide at goggles/quickstart.goggle for the starting point, and the getting started guide covers the syntax, creating, updating, and deleting a Goggle, with sections on fine-tuning, on what happens when two instructions conflict, and on excluding results that do not match. ### Does Brave Search have editorial bias, and what do Goggles do about it? The README says Brave Search does not have editorial biases, but that all search engines have intrinsic bias from the underlying data and from algorithmic choices about which features to select. Goggles let users counter that intrinsic bias in the ranking and build search experiences an all-purpose engine could not cover. ## Sources - [brave/goggles-quickstart on GitHub](https://github.com/brave/goggles-quickstart) - [Issues](https://github.com/brave/goggles-quickstart/issues) - [Project website](https://search.brave.com/goggles) - [README](https://github.com/brave/goggles-quickstart/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brave-goggles-quickstart