krz/crumb
A local alternative to your browser's history.
clone: git clone https://gitbay.org/krz/crumb.git
532e20db6ebef5e4257f437b3ab7429fa18637b3
verified · cmc
author: Christian Cleberg <hello@cleberg.net> · 2025-08-02T18:01:20Z
README.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.org | 102 ---------------------------------------------------------- 2 files changed, 106 insertions(+), 102 deletions(-) new file mode 100644 @@ -0,0 +1,106 @@ +[](https://deepwiki.com/ccleberg/crumb) + +Crumb is a local-only browser history tracker. It consists of two parts: +a WebExtension-based browser plugin and a local HTTP server. Crumb logs +each visited web page to a plaintext file in Org-mode format. + +# Components + +- Browser extension (WebExtension API, JavaScript) +- Local HTTP listener (Python + Flask) +- Plaintext log file (~/.crumb/history.log) + +# Functionality + +Each time a page is loaded in the browser, the extension sends the page +metadata to the local server. The server appends this data to a +structured log file. + +Data captured per page: + +- Page title +- URL +- Timestamp (UTC) +- Hostname +- Path +- Optional: query string, tab ID, window ID, favicon URL + +The log is formatted as an Org-mode file, with one top-level heading per +visit and standard `:PROPERTIES:` metadata. + +# Requirements + +- Python 3.x +- Flask +- A Chromium-based or Firefox browser with extension developer mode + enabled + +# Usage + +1. Start the local listener: + + ``` shell + python3 -m venv venv + source ./venv/bin/activate + pip install -r requirements.txt + python server.py + ``` + +2. Load the extension into your browser: + + - Enable Developer Mode + - Load the `crumb_extension/` directory + +3. Browse the web. Entries will appear in `~/.crumb/history.org` + +4. Search the log using: + + ``` shell + python search.py <term> + ``` + +# Example Log Entry + +``` org +* Example Domain +:PROPERTIES: +:URL: http://example.com +:TIMESTAMP: 2025-06-04T20:31:01.123456 +:HOST: example.com +:PATH: / +:TAB: 143 +:WINDOW: 1 +:FAVICON: https://example.com/favicon.ico +:END: +``` + +# Preview Images + +Screenshots of Crumb in use. + +<figure> +<img src="./screenshots/devtools.png" /> +<figcaption>Developer Console Output</figcaption> +</figure> + +<figure> +<img src="./screenshots/history.png" /> +<figcaption>Org-Mode History Log</figcaption> +</figure> + +<figure> +<img src="./screenshots/search.png" /> +<figcaption>Search Utility in Terminal</figcaption> +</figure> + +# Limitations + +- Browser extensions cannot write files directly; communication requires + the local server. +- History is stored in plaintext and is not encrypted. You can bolt-on a + third-party encryption tool, if required. +- Data is stored locally and is never transmitted externally. + +# License + +GPL 3.0 License. See LICENSE file. deleted file mode 100644 @@ -1,102 +0,0 @@ -#+TITLE: Crumb -#+AUTHOR: Christian Cleberg -#+OPTIONS: toc:nil - -[[https://deepwiki.com/ccleberg/crumb][https://deepwiki.com/badge.svg]] - -Crumb is a local-only browser history tracker. It consists of two parts: a -WebExtension-based browser plugin and a local HTTP server. Crumb logs each -visited web page to a plaintext file in Org-mode format. - -* Components - -- Browser extension (WebExtension API, JavaScript) -- Local HTTP listener (Python + Flask) -- Plaintext log file (~/.crumb/history.log) - -* Functionality - -Each time a page is loaded in the browser, the extension sends the page metadata -to the local server. The server appends this data to a structured log file. - -Data captured per page: - -- Page title -- URL -- Timestamp (UTC) -- Hostname -- Path -- Optional: query string, tab ID, window ID, favicon URL - -The log is formatted as an Org-mode file, with one top-level heading per visit -and standard =:PROPERTIES:= metadata. - -* Requirements - -- Python 3.x -- Flask -- A Chromium-based or Firefox browser with extension developer mode enabled - -* Usage - -1. Start the local listener: - - #+BEGIN_SRC shell - python3 -m venv venv - source ./venv/bin/activate - pip install -r requirements.txt - python server.py - #+END_SRC - -2. Load the extension into your browser: - - - Enable Developer Mode - - Load the =crumb_extension/= directory - -3. Browse the web. Entries will appear in =~/.crumb/history.org= - -4. Search the log using: - - #+BEGIN_SRC shell - python search.py <term> - #+END_SRC - -* Example Log Entry - -#+BEGIN_SRC org -* Example Domain -:PROPERTIES: -:URL: http://example.com -:TIMESTAMP: 2025-06-04T20:31:01.123456 -:HOST: example.com -:PATH: / -:TAB: 143 -:WINDOW: 1 -:FAVICON: https://example.com/favicon.ico -:END: -#+END_SRC - -* Preview Images - -Screenshots of Crumb in use. - -#+CAPTION: Developer Console Output -[[./screenshots/devtools.png]] - -#+CAPTION: Org-Mode History Log -[[./screenshots/history.png]] - -#+CAPTION: Search Utility in Terminal -[[./screenshots/search.png]] - -* Limitations - -- Browser extensions cannot write files directly; communication requires the - local server. -- History is stored in plaintext and is not encrypted. You can bolt-on a - third-party encryption tool, if required. -- Data is stored locally and is never transmitted externally. - -* License - -GPL 3.0 License. See LICENSE file.