Commit `532e20db6e`

532e20db6ebef5e4257f437b3ab7429fa18637b3

parent: 3430a044cc

Verified · cmc

cmc <hello@cleberg.net> · 2025-08-02 18:01 UTC

fix: convert README.org to README.md

Layout: unified · split

README.md added +106

@@ -0,0 +1,106 @@
	1	[![](https://deepwiki.com/badge.svg)](https://deepwiki.com/ccleberg/crumb)
	2
	3	Crumb is a local-only browser history tracker. It consists of two parts:
	4	a WebExtension-based browser plugin and a local HTTP server. Crumb logs
	5	each visited web page to a plaintext file in Org-mode format.
	6
	7	# Components
	8
	9	- Browser extension (WebExtension API, JavaScript)
	10	- Local HTTP listener (Python + Flask)
	11	- Plaintext log file (~/.crumb/history.log)
	12
	13	# Functionality
	14
	15	Each time a page is loaded in the browser, the extension sends the page
	16	metadata to the local server. The server appends this data to a
	17	structured log file.
	18
	19	Data captured per page:
	20
	21	- Page title
	22	- URL
	23	- Timestamp (UTC)
	24	- Hostname
	25	- Path
	26	- Optional: query string, tab ID, window ID, favicon URL
	27
	28	The log is formatted as an Org-mode file, with one top-level heading per
	29	visit and standard `:PROPERTIES:` metadata.
	30
	31	# Requirements
	32
	33	- Python 3.x
	34	- Flask
	35	- A Chromium-based or Firefox browser with extension developer mode
	36	enabled
	37
	38	# Usage
	39
	40	1. Start the local listener:
	41
	42	``` shell
	43	python3 -m venv venv
	44	source ./venv/bin/activate
	45	pip install -r requirements.txt
	46	python server.py
	47	```
	48
	49	2. Load the extension into your browser:
	50
	51	- Enable Developer Mode
	52	- Load the `crumb_extension/` directory
	53
	54	3. Browse the web. Entries will appear in `~/.crumb/history.org`
	55
	56	4. Search the log using:
	57
	58	``` shell
	59	python search.py <term>
	60	```
	61
	62	# Example Log Entry
	63
	64	``` org
	65	* Example Domain
	66	:PROPERTIES:
	67	:URL: http://example.com
	68	:TIMESTAMP: 2025-06-04T20:31:01.123456
	69	:HOST: example.com
	70	:PATH: /
	71	:TAB: 143
	72	:WINDOW: 1
	73	:FAVICON: https://example.com/favicon.ico
	74	:END:
	75	```
	76
	77	# Preview Images
	78
	79	Screenshots of Crumb in use.
	80
	81	<figure>
	82	<img src="./screenshots/devtools.png" />
	83	<figcaption>Developer Console Output</figcaption>
	84	</figure>
	85
	86	<figure>
	87	<img src="./screenshots/history.png" />
	88	<figcaption>Org-Mode History Log</figcaption>
	89	</figure>
	90
	91	<figure>
	92	<img src="./screenshots/search.png" />
	93	<figcaption>Search Utility in Terminal</figcaption>
	94	</figure>
	95
	96	# Limitations
	97
	98	- Browser extensions cannot write files directly; communication requires
	99	the local server.
	100	- History is stored in plaintext and is not encrypted. You can bolt-on a
	101	third-party encryption tool, if required.
	102	- Data is stored locally and is never transmitted externally.
	103
	104	# License
	105
	106	GPL 3.0 License. See LICENSE file.

README.org deleted −102

	@@ -1,102 +0,0 @@
1	#+TITLE: Crumb
2	#+AUTHOR: Christian Cleberg
3	#+OPTIONS: toc:nil
4
5	[[https://deepwiki.com/ccleberg/crumb][https://deepwiki.com/badge.svg]]
6
7	Crumb is a local-only browser history tracker. It consists of two parts: a
8	WebExtension-based browser plugin and a local HTTP server. Crumb logs each
9	visited web page to a plaintext file in Org-mode format.
10
11	* Components
12
13	- Browser extension (WebExtension API, JavaScript)
14	- Local HTTP listener (Python + Flask)
15	- Plaintext log file (~/.crumb/history.log)
16
17	* Functionality
18
19	Each time a page is loaded in the browser, the extension sends the page metadata
20	to the local server. The server appends this data to a structured log file.
21
22	Data captured per page:
23
24	- Page title
25	- URL
26	- Timestamp (UTC)
27	- Hostname
28	- Path
29	- Optional: query string, tab ID, window ID, favicon URL
30
31	The log is formatted as an Org-mode file, with one top-level heading per visit
32	and standard =:PROPERTIES:= metadata.
33
34	* Requirements
35
36	- Python 3.x
37	- Flask
38	- A Chromium-based or Firefox browser with extension developer mode enabled
39
40	* Usage
41
42	1. Start the local listener:
43
44	#+BEGIN_SRC shell
45	python3 -m venv venv
46	source ./venv/bin/activate
47	pip install -r requirements.txt
48	python server.py
49	#+END_SRC
50
51	2. Load the extension into your browser:
52
53	- Enable Developer Mode
54	- Load the =crumb_extension/= directory
55
56	3. Browse the web. Entries will appear in =~/.crumb/history.org=
57
58	4. Search the log using:
59
60	#+BEGIN_SRC shell
61	python search.py <term>
62	#+END_SRC
63
64	* Example Log Entry
65
66	#+BEGIN_SRC org
67	* Example Domain
68	:PROPERTIES:
69	:URL: http://example.com
70	:TIMESTAMP: 2025-06-04T20:31:01.123456
71	:HOST: example.com
72	:PATH: /
73	:TAB: 143
74	:WINDOW: 1
75	:FAVICON: https://example.com/favicon.ico
76	:END:
77	#+END_SRC
78
79	* Preview Images
80
81	Screenshots of Crumb in use.
82
83	#+CAPTION: Developer Console Output
84	[[./screenshots/devtools.png]]
85
86	#+CAPTION: Org-Mode History Log
87	[[./screenshots/history.png]]
88
89	#+CAPTION: Search Utility in Terminal
90	[[./screenshots/search.png]]
91
92	* Limitations
93
94	- Browser extensions cannot write files directly; communication requires the
95	local server.
96	- History is stored in plaintext and is not encrypted. You can bolt-on a
97	third-party encryption tool, if required.
98	- Data is stored locally and is never transmitted externally.
99
100	* License
101
102	GPL 3.0 License. See LICENSE file.

Commit 532e20db6e

Commit `532e20db6e`