TimeWarden

Enforce daily time limits on websites. Take control of your browsing habits.

This project was entirely generated and developed by AI (Claude Code, using claude-opus-4-5). Every commit authored by AI is prefixed with (Claude Code) in the subject line and includes the footer Generated by AI (Claude Code, claude-opus-4-5). The full development history -- from initial scaffold through all feature iterations -- was driven by AI with human direction. You can view the complete implementation plans and development journals in the .ai/ directory (git-ignored, available only in local clones).

What Is TimeWarden?

TimeWarden is a Manifest V3 browser extension (Firefox-first, Chrome-compatible) that works like iOS Screen Time for your browser. You configure per-domain daily time limits and the extension tracks your active browsing time, warns you as limits approach, and blocks access when time runs out.

Core principles:

• No cheating -- limits cannot be extended or bypassed once a tracking period has started
• Exact domain matching -- youtube.com does not match music.youtube.com
• Multi-tab awareness -- multiple tabs of the same domain do not drain time faster
• Active engagement only -- only focused tabs (and audible background media) count toward limits
• Zero runtime dependencies -- everything compiles away at build time

Features

• Per-domain daily time limits with second-level precision
• Day-of-week overrides -- set different limits for weekdays vs. weekends (or any individual day)
• Configurable reset times -- choose when each domain's daily counter resets
• Pause functionality -- pause tracking with a configurable daily pause allowance
• Grace period -- a final warning window before hard-blocking a domain
• Blocking page -- a "Time's Up" page showing today's usage stats
• Configurable notification rules -- percentage-based or time-remaining triggers with per-domain overrides and custom messages
• Toolbar badge -- live countdown showing remaining time, pause state, or grace period
• Settings lockdown -- timing fields are locked once a tracking session has started for the current period
• Destructive action confirmation -- disabling a tracked domain requires typing the domain name to confirm
• Revert changes -- undo unsaved edits in settings with a single click
• Dashboard with analytics:
  • Today's overview with live progress bars
  • Historical stacked bar chart (pure SVG, no charting library)
  • Per-domain breakdown
  • Session analytics
  • Blocking statistics
  • Behavioral insights
• Dark mode -- light, dark, or system-preference with class-based toggling
• Keyboard accessibility -- focus-visible styles, ARIA roles, reduced-motion support

Tech Stack

Prerequisites

• Node.js >= 18 (developed on v24)
• pnpm (any recent version; developed on v10)

Getting Started

# Clone the repository
git clone [email protected]:bwnn/timewarden.git
cd timewarden

# Install dependencies
pnpm install

# Build for production
pnpm run build

# Or watch for changes during development
pnpm run dev

The built extension is output to the dist/ directory.

Loading in Firefox

1. Open about:debugging#/runtime/this-firefox
2. Click Load Temporary Add-on...
3. Select any file inside the dist/ directory (e.g. dist/manifest.json)

Loading in Chrome

1. Open chrome://extensions
2. Enable Developer mode
3. Click Load unpacked
4. Select the dist/ directory

Note: Chrome uses the chrome.* namespace. TimeWarden is written against the browser.* API. A polyfill like webextension-polyfill may be needed for full Chrome compatibility -- this has not been thoroughly tested.

Scripts

Project Structure

timewarden/
├── manifest.json              # MV3 browser extension manifest
├── package.json
├── vite.config.ts             # Multi-entry build config with post-build plugin
├── tsconfig.json
├── svelte.config.js
├── static/icons/              # Extension icons (SVG source + PNGs)
└── src/
    ├── app.css                # Tailwind v4 entry + dark mode + a11y
    ├── browser.d.ts           # WebExtension API type declarations
    ├── lib/
    │   ├── types.ts           # All shared TypeScript interfaces
    │   ├── constants.ts       # Defaults, limits, alarm prefixes
    │   ├── utils.ts           # Time formatting, date helpers
    │   ├── domain-matcher.ts  # Exact hostname matching
    │   ├── messaging.ts       # Typed message helpers
    │   └── theme.ts           # Dark mode management
    ├── background/
    │   ├── index.ts           # Service worker entry + message routing
    │   ├── storage-manager.ts # All storage CRUD operations
    │   ├── tab-tracker.ts     # Tab lifecycle + shared state
    │   ├── timer-engine.ts    # Core tracking state machine
    │   ├── reset-manager.ts   # Per-domain reset scheduling
    │   ├── notification-manager.ts
    │   └── block-manager.ts   # Grace period + blocking
    ├── entrypoints/           # HTML entry points for each UI page
    ├── popup/                 # Toolbar popup UI
    ├── settings/              # Full-tab settings page
    ├── dashboard/             # Full-tab analytics dashboard
    └── blocked/               # "Time's Up" blocked page

Architecture

The background service worker is split into six focused modules:

• Tab Tracker -- listens to tab/window events and exports shared state
• Timer Engine -- core state machine that tracks active time using timestamp-based tracking (survives MV3 service worker termination)
• Storage Manager -- all browser.storage.local CRUD with a serialized operation queue to prevent race conditions
• Reset Manager -- schedules per-domain daily resets using browser.alarms
• Notification Manager -- dispatches browser notifications based on configurable rules
• Block Manager -- handles grace periods, blocks domains, and intercepts navigation

UI pages communicate with the background via typed messages (browser.runtime.sendMessage). The popup polls for live status updates every second.

Releases

Signed Firefox .xpi files are available on the GitHub Releases page. These can be installed directly in Firefox without any developer settings.

Setup (one-time)

The release workflow signs the extension via the AMO API, which requires API credentials:

1. Log in to addons.mozilla.org
2. Go to Tools > Manage API Keys (or visit https://addons.mozilla.org/developers/addon/api/key/)
3. Generate credentials -- you'll get a JWT issuer and JWT secret
4. Add them as repository secrets in GitHub (Settings > Secrets and variables > Actions):
   • AMO_JWT_ISSUER -- the JWT issuer (API key)
   • AMO_JWT_SECRET -- the JWT secret

Creating a release

Push a version tag:

git tag v1.0.0
git push origin v1.0.0

The GitHub Actions workflow will build the extension, sign it via AMO as an unlisted extension, and attach the signed .xpi to a new release.

Local bundling (unsigned)

For development and testing via about:debugging:

pnpm run bundle:firefox
# Output: web-ext-artifacts/timewarden-<version>.zip

Known Limitations

• No data migration -- upgrading from an older storage format (minutes-based) requires clearing extension data
• Chrome compatibility -- uses browser.* namespace throughout; Chrome support is untested and may require a polyfill
• Badge staleness -- the toolbar badge can be up to 30 seconds stale between tab events
• No keyboard shortcut for pause/resume
• Not published -- the extension is not on any extension store; install via GitHub Releases or load from source

License

This project does not currently include a license.