A wxPython-based graphical interface for browsing the JSONHTL notes system. Provides hypertext navigation, heading rendering, and metadata display in a read-only interface.
# Install dependencies
pip install wxPython requests
# Run from HTTP server
python notes_browser.py --url http://localhost:8021
# Run from local GDBM file
python notes_browser.py --gdbm-file /path/to/notes.gdbmgdata-browser makes the notes system accessible via a graphical interface similar to a web browser. It can connect to either a running gdata HTTP server or a local GDBM database file.
Command-line options:
• --url URL — Connect to gdata HTTP server at URL
• --gdbm-file PATH — Open local GDBM database file
Environment variables (used if no arguments provided):
• NOTES_URL — HTTP server URL
• GDBM_FILE — Path to GDBM file
Default behaviour: Looks for .agent_notes.gdbm in current directory, then falls back to http://127.0.0.1:8021.
• Hypertext Navigation: Links are styled distinctly and navigate to target pages when clicked
• Heading Rendering: JSON fields named title, heading, h1 render as formatted headings; Markdown-style headings also supported
• Inline Markup: Markdown-style **bold**, `code`, and *italic* in text strings are rendered with appropriate formatting
• Metadata Display: System fields (created, modified, type, version) shown in separate metadata table
• Navigation History: Back/Forward buttons maintain browsing history like a web browser
• File Menu: Open any page by name using Ctrl+O or File > Open Page
• Read-Only Interface: Safe browsing without risk of accidental modifications
As of version 5, the browser no longer fetches the full list of document keys ("Total pages") on every page navigation. This operation is expensive, especially for large note collections, and can cause unnecessary load on the server. Avoid triggering a scan of all keys unless it is critical to the coding request or user action. If you need a list of all notes, use the dedicated list function or menu item, not on every page view.
• Ctrl+O — Open a page by name
• Ctrl+H — Go home (root page)
• Alt+Left — Back
• Alt+Right — Forward
• F5 — Refresh current page
• Ctrl+Q — Exit application
The browser consists of three main components:
• NotesDataSource — Abstract data access layer supporting both GDBM and HTTP backends
• NotesHTMLRenderer — Converts JSON documents to displayable HTML with proper heading, link, and metadata rendering
• NotesBrowser — Main wxPython UI class managing navigation, menu bar, history, and HTML display
• Read-Only First: Version 1.0 focuses on safe browsing. Edit functionality can be added in future versions with appropriate safeguards.
• Dual Backend Support: Supporting both HTTP and GDBM enables use cases including offline browsing and direct server integration.
• Custom Navigation Protocol: Links use navigate:// protocol to distinguish internal note navigation from external URLs.
• HTML Rendering via wx.html.HtmlWindow: Provides rich formatted content display with custom link handling.
• Stack-Based History: Simple history stack matches familiar web browser navigation patterns.
✓ Hypertext navigation with styled links
✓ Heading rendering (JSON fields and Markdown syntax)
✓ Metadata display in separate table
✓ Navigation history (back/forward)
✓ File > Open menu item
✓ Read-only browsing interface
✓ Refresh button and F5 shortcut
✓ Inline markup rendering (bold, code, italic)
○ Search functionality (planned)
○ Edit mode (planned)
○ Backlinks/reverse references (planned)
○ Note templates (planned)