Home

Home

This page is the front door to the wiki: what raindrop-brave-sync is, who it is for, and where every other page fits.

What it is

raindrop-brave-sync reads a Raindrop.io bookmark library with an LLM, works out what each save was actually about, and files it into a taxonomy that was generated from that same library on the first run and pinned ever since. It writes the resulting collections and tags back to Raindrop, then stages a small, heavily filtered set of promotions for Brave's bookmarks bar, where they appear in the running browser within about a minute (through an unpacked extension) or at the next Brave start (through a launchd agent that rewrites the bookmarks file). It is additive by construction: every node it creates is marked as its own, it never deletes a bookmark you made, and it never moves or renames anything you placed by hand.

Two halves, deliberately split

• Phase A, classify. Network and LLM work, never a browser file. It runs as a Claude Code skill (/raindrop-sync) in an interactive session with a Raindrop connector. This half needs an LLM session and has no fallback: there is no keyword-rules mode, no local-model mode and no classify-by-domain mode. If you are not willing to run a model over your bookmark titles and URLs, the classification half has nothing to offer you.
• Phase B, apply. Browser work, never the network. It is plain Python from the standard library (apply_brave.py and native_host.py, no venv, no pip, no dependencies) plus a single-file MV3 extension that you load unpacked once. It runs unattended, and it runs just as well on a desired.json you wrote by hand.

The only thing that passes between them is one file, ~/.raindrop-sync/desired.json. Architecture explains why the seam is there and what each side is forbidden to touch.

Who it is for

• You keep a Raindrop library that has decayed into a few hundred undifferentiated links, and you want it classified with judgement rather than keyword rules.
• You have a bookmarks bar you built by hand, and you want additions filed into it with no risk to what is already there.
• You run macOS with Brave, are comfortable in a terminal, and use Claude Code.

It is not for you if you need Windows or Linux (launchd, the macOS keychain and macOS profile paths are baked in), if you want Safari (not "not yet": every route was tested and closed, see the FAQ), if you want deletions mirrored from Raindrop, or if you expect a taxonomy to come in the box. Yours is generated from your own library. The examples used throughout this wiki (Recipes, Woodworking, Research Papers, Travel) are invented placeholders and will not appear in your install.

Read this first

The README says it and the wiki agrees: if you read one file, read RESEARCH.md. Brave hashes bookmark titles as UTF-16LE while every other field is UTF-8. Brave reads native-messaging manifests from Chrome's directory, not its own. Packing a .crx permanently poisons your extension id. Nearly every rule in this project that looks arbitrary traces back to a finding in that file, and Research Status tracks which findings are verified, which are derived from Chromium source, and which remain untested.

Pages

Page	What it is for
Home	This page: orientation and the map.
FAQ	Direct answers to the questions people ask first: why an LLM, why no Safari, why unpacked, why poll, why never delete, what the canary is.
Architecture	The two phases, the handoff file, the two appliers, and how they coexist without stepping on each other.
Ledger and File Formats	What lives in state.db, taxonomy.json, collection-map.json and desired.json, plus the shape of Brave's Bookmarks JSON and its checksum.
Taxonomy and Classification	How the first pass builds your taxonomy, why it is pinned afterwards, the no-bin rule, and delta detection by content hash.
Safety and Ownership Model	Marker ownership, the preflight aborts, backups, atomic writes, the promotion gate, and why nothing is ever deleted.
Operations	Day-to-day running: invoking the pass, reading the logs, watching the canary, handling the token, re-verifying after a Brave upgrade.
Troubleshooting	Symptom-first fixes: host not found, a greyed-out extension, bookmarks that appear and vanish, a library that reclassifies on every run.
Glossary	The vocabulary: marker, promotion, delta, canary, pinned taxonomy, applier, client key.
Research Status	Every finding with its verification status (verified, source-derived, untested) and how to reproduce it on a throwaway profile.
Contributing and Roadmap	How to test safely against a copy, what will be declined, and how the public board is organised.

Where to start

• Installing it: SETUP.md is the complete, ordered install, including the three things bootstrap.sh cannot do for you: the Raindrop token, the one-time Load unpacked, and the first classification run that generates your taxonomy. Read it before running anything against a library you care about, and dry-run the file writer against a copy of your Bookmarks file first.
• Understanding it: Architecture, then Safety and Ownership Model.
• Fixing it: Troubleshooting, which is organised by symptom.
• Helping: Contributing and Roadmap. The most useful contribution is a reproduction, or a correction, of a finding in RESEARCH.md.

Links

• Repository: https://github.com/rajatrv-fullstack/raindrop-brave-sync
• README.md: the overview, the design principles, and the honest status and limitations list.
• SETUP.md: the install, the verification checklist, and the built-in troubleshooting entries.
• RESEARCH.md: ten findings established by experiment, with a verification table for every claim.
• CONTRIBUTING.md: how to report a research correction and how to test without touching real data.
• Roadmap board: four columns: what is verified, what needs reproducing on another machine, where other browsers and operating systems need a hand, and what is planned.
• Issues for bugs and research corrections; Discussions for questions.

Verified on macOS 26 with Brave 152, built and running since 2026-09-05, MIT licence.