blob: 6384a1bf70bc961919a5c247bf5b2aa31e942bea (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
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.
|
