Skip to content

Instantly share code, notes, and snippets.

@hughdbrown

hughdbrown/browser-hist.md

Last active July 29, 2025 19:13
Show Gist options
  • Save hughdbrown/a41961047590067e2dbc8f76fb1fe70a to your computer and use it in GitHub Desktop.
Save hughdbrown/a41961047590067e2dbc8f76fb1fe70a to your computer and use it in GitHub Desktop.
Download ZIP
PRD for a browser history app for MacOS + Chrome
Raw
browser-hist.md

Rust CLI Tool: Chrome History Searcher for Mac

TL;DR

Mac users often need to search their Chrome browsing history quickly and flexibly from the command line. This Rust CLI tool enables users to search their Chrome history database by date range, page title, or URL domain, with results displayed in the terminal. The tool is designed for privacy-conscious power users, developers, and researchers who want fast, local, and scriptable access to their browsing data.

Goals

Business Goals

  • Deliver a robust, privacy-respecting CLI tool for local Chrome history search on Mac.

  • Demonstrate Rust’s suitability for safe, high-performance CLI utilities.

  • Increase engagement with developer and power-user communities on Mac.

  • Provide a foundation for future browser data tools or integrations.

User Goals

  • Enable fast, flexible searching of Chrome history by date, title, or URL from the terminal.

  • Ensure all searches are performed locally, with no data leaving the user’s machine.

  • Support scripting and automation by providing clear, structured terminal output.

  • Avoid Chrome database corruption by working on a safe, temporary copy.

  • Minimize setup and learning curve for technical users.

Non-Goals

  • No graphical user interface (GUI) or web interface.

  • No support for browsers other than Chrome (e.g., Firefox, Safari).

  • No cloud sync, remote access, or data export beyond terminal output.

User Stories

Persona 1: Power User / Developer

  • As a developer, I want to search my Chrome history for a specific domain, so that I can quickly find all visits to a site I’m debugging.

  • As a power user, I want to filter my history by date range, so that I can review my browsing activity for a specific project period.

  • As a developer, I want to search for keywords in page titles, so that I can recall resources I’ve previously found useful.

Persona 2: Researcher / Analyst

  • As a researcher, I want to extract all history entries for a given time window, so that I can analyze my browsing patterns.

  • As an analyst, I want to combine multiple filters (date, title, domain), so that I can narrow down large history datasets efficiently.

Persona 3: Privacy-Conscious User

  • As a privacy-conscious user, I want to ensure my browsing data never leaves my machine, so that I can trust the tool with sensitive information.

  • As a user, I want the tool to avoid interfering with Chrome’s operation, so that my browser data remains safe.

Functional Requirements

  • Command-Line Interface (Priority: High)

    • Date Range Option: Allow users to specify a start and end date (YYYY-MM-DD) to filter results by last_visit_time.

    • Title Search Option: Allow users to search for text within the title field.

    • URL Domain Search Option: Allow users to search for a domain or substring within the url field.

    • Help and Usage Output: Provide clear help text and usage examples via --help.

  • Database Handling (Priority: High)

    • Temporary Read-Only Copy: Automatically create a temporary, read-only copy of the Chrome history SQLite file before querying.

    • Safe File Access: Handle file access errors gracefully (e.g., if Chrome is running or file is missing).

  • Query & Output (Priority: High)

    • Flexible Query Construction: Support any combination of the above filters.

    • Full Column Output: Display all columns from the urls table: id, url, title, visit_count, typed_count, last_visit_time.

    • Human-Readable Dates: Convert last_visit_time to YYYY-MM-DD format in output.

    • Tabular Terminal Output: Present results in a clear, aligned table in the terminal.

  • Error Handling & Validation (Priority: High)

    • Input Validation: Validate date formats and required arguments.

    • Graceful Error Messages: Provide actionable error messages for missing files, invalid input, or no results.

  • Performance & Extensibility (Priority: Medium)

    • Efficient Querying: Use indexed queries where possible for responsiveness.

    • Modular Codebase: Structure code for easy future extension (e.g., support for other browsers).

User Experience

Entry Point & First-Time User Experience

  • Users discover the tool via documentation, a README, or a trusted recommendation.

  • Installation is via a single binary download or cargo install.

  • On first run, users invoke the tool with --help to view usage instructions and examples.

  • No onboarding or account setup is required.

Core Experience

  • Step 1: User runs the CLI tool with desired options (e.g., chrome-history-search --date-range 2024-01-01:2024-01-31 --search "Rust" --url "github.com").

    • Minimal friction: clear, concise command-line options.

    • Input validation: tool checks date formats and option combinations.

    • If input is invalid, a clear error message is shown and the process exits.

  • Step 2: Tool locates the Chrome history file at ~/Library/Application Support/Google/Chrome/Default/History.

    • If the file is missing, an error is displayed.

  • Step 3: Tool creates a temporary, read-only copy of the database to avoid file locks or corruption.

    • If Chrome is running and the file is locked, the tool retries or provides a helpful error.

  • Step 4: Tool constructs and executes a SQL query based on user filters.

    • All filters are combined with logical AND.

  • Step 5: Results are formatted into a readable table, with all columns shown and dates in YYYY-MM-DD format.

    • If no results are found, a friendly message is displayed.

  • Step 6: User reviews results in the terminal, optionally pipes or redirects output for further processing.

Advanced Features & Edge Cases

  • Power users can combine multiple filters for precise queries.

  • If the database is corrupted or unreadable, the tool provides a clear error and exits.

  • If Chrome is running and the file cannot be copied, the tool suggests closing Chrome.

  • Handles large result sets by paginating or warning the user if output is very long.

UI/UX Highlights

  • High-contrast, monospace tabular output for readability.

  • Consistent, predictable command-line interface following Unix conventions.

  • All error messages are actionable and non-technical.

  • No color or formatting that would break in basic terminal environments.

  • Accessibility: output is screen-reader friendly.

Narrative

On a busy Monday morning, Alex, a software developer, is trying to recall a technical article about Rust performance optimizations he read last month. He knows he visited the page using Chrome on his Mac, but can’t remember the exact URL or date. Opening Chrome’s built-in history search is slow and clunky, and he wants a faster, more scriptable solution.

Alex installs the Rust CLI Chrome History Searcher and, with a single command, filters his browsing history for January, searching for the keyword “Rust” in page titles. The tool quickly scans his local Chrome history database—without ever touching the live file or risking data loss—and presents a clear, tabular list of matching entries, including URLs, titles, visit counts, and the exact dates he visited each page.

Within seconds, Alex finds the article he was looking for, copies the URL, and gets back to work. He’s impressed by the tool’s speed, privacy, and flexibility, and soon integrates it into his daily workflow for research, debugging, and productivity tracking. The tool saves him time, keeps his data private, and demonstrates the power of well-designed command-line utilities.

Success Metrics

User-Centric Metrics

  • Number of unique users running the tool locally.

  • Frequency of repeat usage per user.

  • User-reported satisfaction (via feedback or surveys).

Business Metrics

  • Number of downloads or installations.

  • Community engagement (e.g., GitHub stars, issues, contributions).

Technical Metrics

  • Query accuracy (percentage of correct results).

  • Error rate (failed runs vs. total runs).

  • Average query execution time (target: <1s for typical queries).

  • Zero incidents of Chrome history corruption.

Tracking Plan

  • Track command invocations (with user opt-in).

  • Log error types and frequencies (locally, for user review).

  • Monitor performance metrics (execution time, result count).

  • Collect anonymized feedback (optional, opt-in).

Technical Considerations

Technical Needs

  • Command-line argument parsing (using clap or similar).

  • SQLite database access and querying.

  • Date parsing and conversion utilities.

  • Terminal table formatting for output.

  • Temporary file handling for safe database access.

Integration Points

  • Chrome history SQLite file at ~/Library/Application Support/Google/Chrome/Default/History.

  • No external APIs or third-party integrations required.

Data Storage & Privacy

  • All data access is local; no data leaves the user’s machine.

  • Temporary database copies are securely deleted after use.

  • No persistent storage or telemetry by default.

Scalability & Performance

  • Designed for single-user, local execution.

  • Should handle history files up to several hundred MB efficiently.

  • Performance optimizations (e.g., indexed queries) as a secondary goal.

Potential Challenges

  • Handling locked or in-use database files if Chrome is running.

  • Ensuring compatibility with future Chrome schema changes.

  • Providing robust error handling for file and query issues.

  • Supporting non-English characters and Unicode in titles/URLs.

Milestones & Sequencing

Project Estimate

  • Extra-small: 1–2 days

Team Size & Composition

  • Extra-small: 1 person who does everything (Product, Engineering, minimal Design).

Suggested Phases

Phase 1: CLI Prototype (0.5 day)

  • Key Deliverables:

    • Command-line argument parsing

    • Basic help/usage output

  • Dependencies:

    • Rust toolchain, clap crate

Phase 2: Database Access & Query (0.5 day)

  • Key Deliverables:

    • Temporary copy of Chrome history file

    • SQLite query logic for all filters

    • Output all columns in terminal

  • Dependencies:

    • rusqlite or similar crate

Phase 3: Output Formatting & Error Handling (0.5 day)

  • Key Deliverables:

    • Tabular terminal output

    • Human-readable date conversion

    • Input validation and error messages

  • Dependencies:

    • Date/time parsing crate

Phase 4: Testing & Polish (0.5 day)

  • Key Deliverables:

    • Manual and automated tests

    • Documentation and usage examples

    • Final code review and packaging

  • Dependencies:

    • None
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment