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`