An expense manager for your YouTube watch time. Categorize what you watch, see where the hours go, and set budgets YouTube itself will respect.
Expense trackers work because they make spending visible: every transaction lands in a category, and the totals tell you something you didn't want to hear. YT Ledger does the same for YouTube. Each video in your watch history becomes a ledger entry, and each category sits on a value ladder from brain rot (0) to courses & lectures (5). It's not about watching less. It's about knowing what the time actually went to.
YT Ledger is a browser extension for Chrome and other Chromium browsers, and for Firefox (Manifest V3, built with Plasmo). Everything stays in your browser.
- A value ladder you can shape. Eight editable default categories, with value derived from their position. Search, create, rename, recolor, reorder by dragging, or archive categories and subcategories directly while categorizing.
- Subcategories. Editable subcategories under every category (e.g. Practical how-tos › Coding), with sensible defaults. Charts show top-level categories and drill down in place.
- Auto-categorization rules. Match by exact channel, channel substring, title keywords, title regex, Shorts and maximum duration. Rules run in priority order (first match wins) and can target a category or a subcategory. Test a rule against your history before saving. Manual categorization always wins over rules.
- Ledger. Every watch event grouped by day, with search, category/subcategory filters, an "uncategorized only" review queue, inline categorization, and bulk edits.
- Overview and Insights. Estimated watch time per range (today, 7, 30, 90 days, all), a daily chart, low-value share, channel rankings, weekday patterns and rule suggestions.
- Weekly budgets. Hours per week per category (subcategory time rolls up into its parent), with three enforcement modes on youtube.com:
- Off: track only, no changes to YouTube.
- Gentle: over-budget videos get an outline and an "over budget" chip, plus a dismissible banner on the watch page.
- Strict: over-budget thumbnails and titles are hidden behind a placeholder (click to reveal), and watch pages show an interstitial with a "Watch anyway" option. Uncategorized videos are never blocked.
- Background sync. Any YouTube visit triggers a sync (at most every couple of minutes) with a 14-day lookback. A manual Sync now lets you choose a shorter or longer lookback.
- Retention. History is kept for one year by default; configurable.
- Export and import. CSV export, JSON backup and restore (file or pasted JSON), and a full data wipe.
- Onboarding. A first-run wizard for categories, starter rules and budgets. If you skip it, mild defaults apply.
- Light and dark themes that follow your system setting.
YT Ledger has no server, account, analytics or telemetry. Your data never leaves your browser.
- All data lives in
chrome.storage.localon your machine. - The only network requests go to
youtube.com, as your own signed-in session, to read your history page and to look up missing video durations from public watch pages.
Permissions requested in the manifest:
| Permission | Why |
|---|---|
storage |
Save your ledger, categories, rules, budgets and settings locally. |
unlimitedStorage |
A year of watch history can exceed the default local storage quota. |
scripting |
Register the page-context script that reads YouTube's own history data. |
Host access: *://*.youtube.com/* |
Read your watch history, look up video durations, and show budget overlays. |
Both browsers let you switch off an extension's access to a site after installing it. If YouTube access is off, nothing syncs and no overlays appear, so the dashboard shows an Allow YouTube access button. On Firefox the add-on also declares that it collects no data.
- Chrome / Brave / Edge: YT Ledger on the Chrome Web Store
- Firefox (128 or later): YT Ledger on Firefox Add-ons
- Download
yt-ledger-v<version>.zipfrom the latest release and unzip it. - Open
chrome://extensions(orbrave://extensions,edge://extensions) and enable Developer mode. - Click Load unpacked and select the unzipped folder.
- Click the YT Ledger toolbar icon to open the dashboard, then visit YouTube once while signed in to run the first sync.
- Download
yt-ledger-v<version>-firefox.zipfrom the latest release. - Open
about:debugging#/runtime/this-firefox, click Load Temporary Add-on… and pick the zip (or themanifest.jsoninside it once unzipped). - Click the YT Ledger toolbar icon to open the dashboard, then visit YouTube once while signed in to run the first sync.
Regular Firefox only keeps add-ons that Mozilla has signed, so a temporary add-on is removed when Firefox restarts. To keep it installed, use Firefox Developer Edition, Nightly or ESR with xpinstall.signatures.required set to false in about:config and install the zip from about:addons → ⚙ → Install Add-on From File… (rename it to .xpi if the file picker greys it out).
The store listings are the recommended install path; the manual steps below always work too.
Requires Node.js and pnpm.
git clone https://github.com/sankalpmukim/yt-history-poc.git
cd yt-history-poc
pnpm install
pnpm build # → build/chrome-mv3-prod (load this folder unpacked)
pnpm build:firefox # → build/firefox-mv3-prod (load its manifest.json in about:debugging)pnpm dev # development build with live reload → build/chrome-mv3-dev
pnpm dev:firefox # same for Firefox → build/firefox-mv3-dev
pnpm build # production build → build/chrome-mv3-prod
pnpm build:firefox # production build → build/firefox-mv3-prod
pnpm package # production zip → build/chrome-mv3-prod.zip
pnpm package:firefox # production zip → build/firefox-mv3-prod.zip
pnpm test # unit tests (node:test)
pnpm e2e # Playwright end-to-end tests: throwaway Chromium profile, plus Firefox if installed
pnpm e2e:firefox # only the Firefox projects
pnpm qa:seed # regenerate the test fixtures in fixtures/Project layout:
background.ts background (service worker in Chrome, event page in Firefox): single writer for storage, sync coordinator, duration resolver
contents/ content scripts on youtube.com
history-sync.ts isolated-world script: talks to the page script, forwards results
history-main.ts page-context script: reads your history page's own data
budget-guard.ts Gentle / Strict budget overlays
core/ pure, unit-tested logic: merge, rules, aggregation, budgets, insights, retention, import/export
tabs/ the dashboard (React): Overview, Ledger, Rules, Categories, Insights, Budgets, Settings, onboarding
e2e/ Playwright specs fixtures/ deterministic test data
qa/ QA checklist and docs docs/ design plan and screenshots
See qa/README.md for how testing works, and docs/PLAN.md for the original design.
YouTube has no public API for watch history, so YT Ledger reads it the same way your browser displays it:
- When you visit any YouTube page, a content script asks the service worker for a sync. If no history tab is open, the worker opens
youtube.com/feed/historyin a background tab and closes it when the sync is done. - A page-context script reads the history page's own server-rendered data (
ytInitialData), plus its continuation pages, within your signed-in session. It collects day-grouped entries going back over the lookback window. - The service worker merges the entries into the local ledger and counts rewatches as separate watch events. It then applies your rules and fills in missing durations from public watch pages.
- Watch time is estimated: video duration × watched progress (from YouTube's progress bar) × number of watch events. YouTube only exposes day-level history, so times within a day are approximate.
- The budget guard compares this week's time per category against your budgets and decorates matching YouTube items in Gentle or Strict mode.
- Chrome/Chromium and Firefox 128+. Tested in Brave, Chromium and Firefox; should work in Chrome, Edge and other Chromium browsers. Safari isn't supported.
- Depends on YouTube's page structure. The history data format is undocumented and changes over time. The parser is defensive, but a YouTube change can break syncing until the parser is updated.
- Estimates, not exact time. Watch time comes from duration × progress, and history is only day-granular.
- Watch history must be on. If YouTube watch history is paused for your account, there's nothing to read.
- No toolbar popup. The toolbar icon opens the full dashboard in a tab.
Issues and pull requests are welcome. Before opening a PR, run pnpm test and pnpm build, and run pnpm e2e if you changed the dashboard or overlays. Keep logic in core/ pure and covered by unit tests.
License: TBD. The bundled Source Serif 4 and Public Sans fonts are licensed under the SIL Open Font License 1.1 (Source Serif 4, Public Sans).


