Skip to content

README.md

Latest commit

 

History

History
326 lines (228 loc) · 9.56 KB

README.md

File metadata and controls

326 lines (228 loc) · 9.56 KB

breadcrumb ›

A minimal Chrome extension that remembers why you opened every tab

Chrome Extension Manifest V3 License Vanilla JS No Dependencies

Install Extension · See How It Works · Report Bug · Request Feature

📸 Screenshots

Breadcrumb popup — tracked tabs with reasons and priority      Breadcrumb overlay prompt asking why you opened the tab

Left: Tracked tab overview  ·  Right: Drop-a-crumb overlay on a new tab

📋 Table of Contents

😤 The Problem

You open a tab with a purpose. Then you open seven more. By the time you come back, you've forgotten what you were doing — and that tab sits there forever, one of twenty ghosts you're too afraid to close.

Breadcrumb solves this with one question: why did you open this?

✨ Features

🎯 Core Features

  • 🍞 Auto-prompt on every new tab
  • 📌 Reasons + tags + priority per tab
  • ⏰ Reminders at 15m / 30m / 1h / tomorrow
  • 😴 Snooze — push the reminder back
  • ✓ Done — marks complete and closes the tab

🛠️ Built Right

  • 🔒 100% local — no servers, no accounts
  • 🚫 Zero inline handlers — fully CSP-compliant
  • ⚡ No build step — pure Manifest V3
  • 📦 No dependencies — vanilla JS only
  • 🌑 Dark theme — easy on the eyes

🔄 How It Works

open new tab
      │
      ▼
 "why this tab?" overlay appears
      │
      ▼
 type a reason → pick priority → set reminder time
      │
      ▼
 crumb saved locally in chrome.storage
      │
      ▼
 alarm fires at your chosen time
      │
      ▼
 notification: "did you finish: 'compare prices before buying'?"
      │
      ├──  ✓ done   →  tab closes, crumb removed
      └──  snooze   →  reminded again in 15 min

Priority system

Indicator Priority When to use
🔴 Red stripe High Need this before end of day
🟡 Amber stripe Medium Getting to it soon
🟢 Green stripe Low Nice to have, no rush

🚀 Installation

Load unpacked (Developer Mode)

1️⃣ Download the extension

git clone https://github.com/yourusername/breadcrumb.git

Or download breadcrumb-extension.zip from Releases and unzip it

2️⃣ Open Chrome extensions

chrome://extensions

3️⃣ Enable Developer Mode

Toggle the switch in the top-right corner of the extensions page

4️⃣ Load the folder

Click Load unpacked → select the breadcrumb-extension folder

5️⃣ Done

The › icon appears in your toolbar. Open any new tab and Breadcrumb will ask why. 🎉

📂 Project Structure

breadcrumb-extension/
│
├── 📄 manifest.json           # Manifest V3 config
│
├── 📁 icons/                  # Extension icons
│   ├── icon16.png             # Toolbar icon
│   ├── icon48.png             # Extensions page icon
│   └── icon128.png            # Chrome Web Store icon
│
└── 📁 src/
    ├── background.js          # Service worker — tab lifecycle, alarms, notifications
    ├── content.js             # Injected overlay prompt on new tabs
    ├── popup.html             # Extension popup UI (IBM Plex, dark theme)
    ├── popup.js               # Popup logic — CSP-safe, event delegation only
    └── options.html           # Options page

🔐 Permissions

Permission Why it's needed
tabs Read tab URLs, titles, and favicons
storage Save crumbs and settings locally on your device
alarms Schedule reminder notifications
notifications Show reminder popups with action buttons
scripting Inject the prompt overlay into new tabs
activeTab Access the currently active tab from the popup

No data ever leaves your device. These permissions are the minimum required.

🛠️ Tech

JavaScript Chrome IBM Plex CSS3

Layer Choice Why
Language Vanilla JS (ES2020) No build step, instant load
Extension API Manifest V3 Current standard, service workers
Storage chrome.storage.local Local-only, persistent across sessions
Reminders chrome.alarms Survives browser restarts
Notifications chrome.notifications Native action buttons (Done / Snooze)
Typography IBM Plex Sans + Mono Crisp, readable, developer aesthetic
Event handling addEventListener + delegation Fully CSP-compliant, no inline handlers

🔒 Privacy

  • ✅ All data stored locally via chrome.storage.local
  • ✅ No external network requests of any kind
  • ✅ No analytics or telemetry
  • ✅ No accounts or sign-in required
  • ✅ Uninstalling removes all data automatically

📦 Publishing to Chrome Web Store

1️⃣ Zip the extension

zip -r breadcrumb.zip breadcrumb-extension/

2️⃣ Go to the Developer Dashboard

chrome.google.com/webstore/devconsole

3️⃣ Upload

Click New Item → upload breadcrumb.zip

4️⃣ Fill in the listing

Add a name, description, category (Productivity), and screenshots

5️⃣ Submit

Review typically takes 1–3 business days. One-time $5 developer fee if not already registered.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

Issues Pull Requests Forks

1️⃣ Fork the repository

2️⃣ Create your feature branch

git checkout -b feature/your-feature-name

3️⃣ Commit your changes

git commit -m "add: your feature description"

4️⃣ Push to the branch

git push origin feature/your-feature-name

5️⃣ Open a Pull Request 🎉

Good first issues

  • Adding keyboard shortcuts to the prompt overlay
  • Supporting Firefox (WebExtensions API)
  • Tag suggestions based on URL hostname patterns
  • Export / import all crumbs as JSON

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

MIT License — Copyright (c) 2024

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software to deal in the Software without restriction, including the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software.

📧 Contact

Let's connect 🤝

Website GitHub LinkedIn Twitter Email

If Breadcrumb saved you from tab chaos, give it a ⭐️

built to fix the too-many-tabs problem, once and for all

vanilla js  ·  manifest v3  ·  zero dependencies  ·  fully local