TimeMachine is an open-source Chrome extension with a Node.js backend designed to help you understand and optimize your digital time usage. It automatically tracks website activity, provides insightful analytics, enables focus management, and generates comprehensive reports—all while respecting your privacy.
Built for developers, students, remote workers, and anyone seeking better digital wellness.
- Automatic Time Tracking - Monitors active tab time with minute-level precision
- Focus Sessions - Pomodoro-style timers with pause/resume controls
- Smart Blocking - Website and keyword filtering to minimize distractions
- Rich Analytics - Daily, weekly, and monthly productivity insights
- PDF & Email Reports - Comprehensive summaries with charts and statistics
- Privacy-First - Only domains and durations stored, no full URLs
- Customizable Themes - 7 built-in themes to match your preferences
Visit our official landing page: https://harshdev625.github.io/TimeMachine/
The landing page showcases:
- 📊 Interactive feature demos with screenshots
- 🎨 Visual design and theming examples
- 📱 Live analytics dashboard preview
- 🚀 Quick installation guide
- 💡 Use cases and benefits
Source: The landing page is built with HTML5, CSS3, and vanilla JavaScript. Source files are in the docs/ directory.
- Automatic Monitoring - Tracks active tab time in real-time (minute-level granularity)
- Timezone Support - Local time tracking for accurate day boundaries
- Category Classification - Organize sites into Work, Social, Entertainment, Professional, or Other
- Multi-View Dashboard - Daily, weekly, and monthly analytics
- Quick Insights - Top sites, focus vs leisure ratio, balance score, category distribution
- Productivity Scoring - Algorithmic score based on category weights
- Focus Sessions - Preset timers with full controls (start, pause, resume, stop)
- Daily Statistics - Track focus time trends
- Theme-Aware Interface - Seamless integration with chosen theme
- Website Blocking - Block distracting domains
- Keyword Filtering - Optional in-page keyword scanning
- Quick Block - One-click blocking for current site
- Custom Blocked Page - Informative page with action buttons (Go Back, Start Focus, Open Dashboard)
- Privacy Toggle - Enable/disable keyword scanning as needed
- PDF Reports - Comprehensive summaries with:
- Key insights and productivity metrics
- Ranked domain table with session statistics
- Category distribution charts
- Time-based visualizations
- Email Integration - Automated reports via EmailJS (HTML format with charts)
- Local Scheduling - Daily, weekly, or monthly report triggers (no external dependencies)
- Solver Tracker - Log problem-solving sessions with categories
- Offline Support - Local buffering with automatic retry and sync
- Authentication - Simple email/password with 30-day JWT tokens
- Feedback System - In-app authenticated feedback submission
- 7 UI Themes - Light, Dark, Cyberpunk, Minimal, Ocean, Sunset, Forest
- In-App Guide - Built-in help documentation
📋 Latest Release: See CHANGELOG.md for version history and recent updates.
Important for Contributors: Understanding our tech stack helps you get started quickly!
- Languages: JavaScript (ES6+), HTML5, CSS3
- Manifest: Chrome Extension Manifest V3
- Charts: Chart.js (interactive visualizations)
- Architecture: Modular design with service workers
- Styling: Custom CSS with theme system (7 themes)
- Runtime: Node.js (v14+)
- Framework: Express.js
- Database: MongoDB with Mongoose ODM
- Authentication: JWT (JSON Web Tokens), bcrypt
- Reports: PDFKit (PDF generation), quickchart-js (charts)
- Email: EmailJS Integration
- Version Control: Git & GitHub
- Package Manager: npm
- Testing: Manual testing + Chrome DevTools
- Deployment: Chrome Web Store (extension), Self-hosted (backend)
| Library | Purpose | Version |
|---|---|---|
express |
Backend API framework | ^4.18.0 |
mongoose |
MongoDB object modeling | ^8.0.0 |
jsonwebtoken |
JWT authentication | ^9.0.0 |
bcrypt |
Password hashing | ^5.1.0 |
pdfkit |
PDF report generation | ^0.15.0 |
chart.js |
Frontend charting | ^4.4.0 |
quickchart-js |
Server-side chart images | ^3.1.3 |
┌─────────────────────────────────────┐
│ Chrome Extension (Frontend) │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Popup UI │ │ Content │ │
│ │ (HTML/CSS) │ │ Scripts │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ ┌──────┴─────────────────┴───────┐ │
│ │ Background Service Worker │ │
│ │ (Time Tracking Logic) │ │
│ └────────────────┬───────────────┘ │
└───────────────────┼──────────────────┘
│
│ REST API (HTTPS)
│ JWT Authentication
│
┌───────────────────▼──────────────────┐
│ Node.js + Express Backend │
│ │
│ ┌────────────┐ ┌──────────────┐ │
│ │ Routes │ │ Models │ │
│ │ (API) │──▶│ (Mongoose) │ │
│ └────────────┘ └──────┬───────┘ │
│ │ │
│ ┌────────────┐ │ │
│ │ Utils │ │ │
│ │ (Timezone, │ │ │
│ │ Validation)│ │ │
│ └────────────┘ │ │
└─────────────────────────┼───────────┘
│
▼
┌─────────────────────────┐
│ MongoDB Database │
│ │
│ • Users │
│ • TimeData │
│ • FocusSessions │
│ • BlockedSites │
│ • Feedback │
└─────────────────────────┘
Install from Chrome Web Store (Recommended) 🌟
- Visit Chrome Web Store
- Click "Add to Chrome"
- Click the extension icon and sign up with email/password
- Start browsing - tracking happens automatically
Basic Usage 📱
- View analytics in the Analytics tab
- Start focus sessions in the Focus tab
- Block distractions in the Guard tab
- Generate reports in the Summary tab
- Click the ? button anytime for help
Backend Setup
# Clone repository
git clone https://github.com/HarshDev625/TimeMachine.git
cd TimeMachine/backend
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env and set:
# - MONGODB_URI=mongodb://localhost:27017/timemachine
# - JWT_SECRET=your-secret-key
# Start development server
npm run devExtension Setup
- Open Chrome and navigate to
chrome://extensions - Enable "Developer mode" (top right toggle)
- Click "Load unpacked"
- Select the
extensionfolder from the cloned repository - The extension icon will appear in your toolbar
TimeMachine/
backend/
index.js # Express server entry point
models/
User.js # User schema (email, password, settings)
TimeData.js # Time tracking data schema
FocusSession.js # Focus session records
BlockedSite.js # Blocked websites/keywords
Feedback.js # User feedback
routes/
auth.js # Authentication endpoints
timeData.js # Time tracking API
focusSessions.js # Focus management API
blockedSites.js # Guard/blocking API
report.js # PDF generation
feedback.js # Feedback API
utils/
validation.js # Input validation
timezone.js # Timezone utilities
extension/
manifest.json # Extension configuration
background.js # Service worker (tracking logic)
popup.html # Main UI
popup.js # UI controller
auth.js # Authentication helper
config.js # API configuration
blocked.html # Blocked page template
blocked.js # Blocked page logic
content-blocker.js # Content script for keyword blocking
report-scheduler.js # Report scheduling logic
modules/
api.js # API client
analytics-tab.js # Analytics functionality
focus-tab.js # Focus session management
guard-tab.js # Blocking controls
summary-tab.js # Summary & reports
solver-tab.js # Problem solver tracker
utils.js # Shared utilities
css/ # Stylesheets
docs/ # Landing page (GitHub Pages)
index.html # Landing page HTML
assets/ # Images and icons
css/style.css # Landing page styles
js/main.js # Landing page scripts
POST /api/auth/signup- Create new user accountPOST /api/auth/login- Login and receive JWT tokenPOST /api/auth/verify- Verify JWT tokenGET /api/auth/profile- Get user profilePOST /api/auth/update-settings- Update user settingsPOST /api/auth/google- Google OAuth 2.0
POST /api/time-data/sync- Sync tracking data (batch)GET /api/time-data/report/:email- Get time data for date rangePATCH /api/time-data/category- Update domain category
POST /api/report/generate- Generate PDF report
POST /api/focus-sessions- Create focus sessionGET /api/focus-sessions/:email- Get user's focus sessions
GET /api/blocked-sites/:email- Get blocked sites listPOST /api/blocked-sites- Add blocked site/keywordDELETE /api/blocked-sites/:id- Remove blocked item
POST /api/feedback/submit- Submit feedbackGET /api/feedback/my- Get user's feedbackGET /api/feedback/all- Get all feedback (admin)PATCH /api/feedback/status/:id- Update feedback status (admin)
For integrating it in this project please follow Google OAuth Instructions
User
{
email: String,
password: String (bcrypt hashed),
role: String (default: 'user'),
settings: {
receiveReports: Boolean,
reportFrequency: String,
categories: Map
},
timezone: {
name: String,
offset: Number
},
lastActive: Date
}TimeData (unique per user/date/domain)
{
userEmail: String,
date: String (YYYY-MM-DD),
domain: String,
totalTime: Number (milliseconds),
sessions: [{
startTime: Date,
endTime: Date,
duration: Number
}],
category: String,
timezone: String
}The extension uses a sophisticated event-driven tracking system:
-
Session Management
- Tab activation or URL change closes previous session
- New session starts for active domain
- Sessions are buffered locally before sync
-
Sync Strategy
- Incremental flush every 1 minute
- Bulk sync every 5 minutes
- Stale session cutoff at 15 minutes
- Offline support with retry mechanism
-
Time Calculation
- Minute-level granularity
- Local timezone tracking (fixes UTC drift issues)
- Idle detection with automatic session termination
- Lock screen handling
Configure automated email reports using EmailJS:
- Create account at EmailJS
- Set up email template with variables:
to_email- Recipient addresssubject- Email subjectmessage- HTML content with chartsmessage_text- Plain text fallback
- In extension Settings, enter:
- Service ID
- Template ID
- Public Key
- Test with "Send Test Email" button
- Enable scheduling (daily/weekly/monthly)
Template Tip: Use triple braces {{{message}}} to render HTML without escaping.
We welcome contributions from the community! Here's how you can help make TimeMachine better:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Make your changes and test thoroughly
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Read CONTRIBUTING.md for detailed guidelines
- Follow our Code of Conduct
- Check existing issues before creating new ones
- Include screenshots for UI changes
- Test your changes locally
- 🐛 Bug fixes - Help us squash bugs
- ✨ New features - Add cool functionality
- 📚 Documentation - Improve guides and docs
- 🎨 UI/UX - Make it more beautiful and user-friendly
- 🧪 Testing - Help us maintain quality
We're participating in Hacktoberfest 2025! Look for issues labeled hacktoberfest and join the fun.
Security is a top priority. Current measures:
- Password Security: bcrypt hashing with per-hash salt
- Authentication: JWT tokens with 30-day expiry
- CORS: Restricted to extension origins + localhost (dev)
- Authorization: All endpoints require valid JWT
- Privacy: No full URLs stored, only domains and durations
Found a security issue? Please open a private issue with minimal details and request secure contact. See SECURITY.md for details.
TimeMachine respects your privacy:
- Minimal Data Collection: Only domains and time durations
- No URL Tracking: Full URLs are never stored
- Local First: Data buffered locally before sync
- Optional Features: Keyword scanning can be disabled
- User Control: Delete data anytime
- No Third-Party Tracking: No analytics or ads
Read our complete Privacy Policy for details.
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: This README + in-app guide
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Website: https://harshdev625.github.io/TimeMachine/
- Chart.js - Beautiful charts and visualizations
- QuickChart - Server-side chart generation for reports
- PDFKit - PDF generation
- EmailJS - Email integration
- All Contributors - Thank you for your contributions!
Built with ❤️ by the open-source community