Skip to main content

Bowerbird

Like its namesake bowerbird, it collects — then, unlike you, it curates. Bowerbird audits, cleans, categorises and helps you rediscover your browser bookmarks, entirely on your own machine.

pip install bowerbird-bookmarks
bowerbird ingest  # read your browsers' bookmarks (read-only)
bowerbird check   # validate every link
bowerbird serve   # dashboard at http://127.0.0.1:8420

What it does

  • Multi-browser ingest — Chrome, Brave, Edge, Vivaldi (one Chromium parser), Firefox (places.sqlite) and Safari (read-only). Sources are facets, not silos: the same link saved in two browsers is one URL, tracked once.
  • Link validation that doesn't lie: only 404/410 (or a confirmed soft-404) counts as dead; a bot-wall 403 is blocked, not dead; reaching a login page counts as alive; YouTube videos are checked via oEmbed because deleted videos still return 200.
  • Canonicalisation and duplicate detection (tracking params stripped, youtu.be unified, per-source dupe groups with a keeper heuristic).
  • LLM thematic analysis (Claude, two-pass): a taxonomy is derived from your collection first, then bookmarks are assigned 1–3 categories with confidence. Categories are tags — one bookmark can live in many.
  • Full-text search (SQLite FTS5) over titles, URLs, topics, and the visible text of every reachable page.
  • Ask your bookmarks — ask a question, get links from your own collection grouped by theme with a line on why each is relevant. Never answers from the open web.
  • Graveyard & Wayback — dead links get Internet Archive snapshot lookup, per-row or bulk replace, and bulk retire for the unrecoverable.
  • Domain triage — review a whole domain in one decision.
  • Obsidian export — topic notes plus per-bookmark stubs with frontmatter and wikilinks; drop the folder into your vault.
  • Topic map — a force-directed graph of your collection's themes.
  • Safe write-back — regenerate the browser's bookmarks file: duplicates collapsed, dead links moved to a _Graveyard folder (never silently deleted), Wayback replacements applied. Dry-run by default, timestamped backup always, refuses to run while the browser is open.

Requirements

  • macOS (browser profile discovery is macOS-path based for now)
  • Python 3.12+
  • An Anthropic API key (ANTHROPIC_API_KEY) for the categorisation and Ask features — everything else works without one.

Data location

Everything lives in $BOWERBIRD_HOME (default ~/.bowerbird): the SQLite database, write-back backups, reports and exports. A bowerbird.db in the current directory is respected. Your browsers' own files are only ever written by the explicit bowerbird writeback --apply, and backed up first.

Commands

Command What it does
bowerbird sync one-shot incremental update: ingest → check → enrich → categorise → index
bowerbird sources detect and register installed browsers
bowerbird ingest import bookmarks + history (read-only, reconciling)
bowerbird check validate links (--recheck to re-probe)
bowerbird enrich fetch page titles/descriptions/text for search
bowerbird categorize --taxonomy / --assign two-pass LLM categorisation
bowerbird index rebuild the full-text search index
bowerbird wayback look up Internet Archive snapshots for dead links
bowerbird report write a Markdown audit report
bowerbird obsidian export an Obsidian-ready folder
bowerbird writeback --source-id N [--apply] write the cleaned tree back
bowerbird serve the dashboard (Library, Ask, Graveyard, Duplicates, Domains, Topic map)

Notes

The CLI is also installed under the short alias bower, and the Python module is import bowerbird.

Status

Beta. Built and used in anger on a 9,600-bookmark collection; APIs and schema may still change. Issues and ideas welcome.

Metadata

Release files for bowerbird-bookmarks 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bowerbird-bookmarks 0.6.2
File Size Uploaded Provenance Actions
bowerbird_bookmarks-0.6.2.tar.gz 39.9 kB Without provenance Details for bowerbird_bookmarks-0.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bowerbird-bookmarks 0.6.2
File Interpreter ABI Platform Actions
bowerbird_bookmarks-0.6.2-py3-none-any.whl Python 3 none any Details for bowerbird_bookmarks-0.6.2-py3-none-any.whl

Total release size: 88.8 kB

Release files / bowerbird_bookmarks-0.6.2.tar.gz

Download URL bowerbird_bookmarks-0.6.2.tar.gz
Size 39.9 kB
Tags Source
SHA-256 checksum
How to use checksums
8bb704fa2de3b9491dcd0fa1f56a2d952e39e69a41ff95968cb6a747bb5aad9a
BLAKE2b-256 checksum
How to use checksums
6a1393d3c158e8ba7bc48c4658d9d2a9db37daef757bffa3b1d5497d3e9a7dad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.0

Release files / bowerbird_bookmarks-0.6.2-py3-none-any.whl

Download URL bowerbird_bookmarks-0.6.2-py3-none-any.whl
Size 48.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b35538ace94830093be736aec172df3103756a2772a07cc7a20cb133101ef72a
BLAKE2b-256 checksum
How to use checksums
22fe462404caf39ee4f4b65bf4e692c2dd48b6b06823c89e920688062c2446d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.0

Security for bowerbird-bookmarks 0.6.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page