Lume ⚡

A powerful desktop application for tracking and visualizing time spent on tasks and applications.

🎨 We Need Your Design Skills!

Calling all UI/UX Designers! We're looking for talented designers to help create a new, unified design system for Lume. If you have experience with Figma and are passionate about productivity tools, we'd love your contribution!

What we need:

• 🎨 Complete UI/UX redesign in Figma
• 🎯 Unified design system and component library
• ✨ Modern, intuitive user experience
• 🌓 Dark and light mode variants
• 📱 Responsive layout considerations

Why Figma? We use the Figma MCP (Model Context Protocol) for seamless design-to-code workflow, making it easier to implement your designs directly into the application.

Interested? Check out our Contributing Guide or open an issue to discuss your design ideas!

---

Lume helps you understand your productivity patterns by automatically tracking time spent on different applications and websites. Get clear insights to improve focus, productivity, and time management.

📸 Screenshots

✨ Features

🎯 Core Tracking

• Cross-platform monitoring - Works on macOS, Windows, and Linux
• Automatic activity tracking - Monitor time spent in applications and websites
• Smart session detection - Detects context switches automatically
• Idle detection - Pauses tracking when you're away
• Timeline view - Visual timeline of your daily activities with summaries

🚀 Productivity Tools

• Productivity Goals - Set daily/weekly goals with progress tracking and notifications
• Pomodoro Timer - Built-in focus timer with customizable work/break intervals
• Tag Management - Organize sessions and goals with custom tags
• Advanced Analytics
  • Calendar heatmap visualization
  • Hourly activity patterns
  • Weekly summaries with trends
  • Behavioral insights and recommendations
  • Daily productivity statistics

⚙️ Customization & Settings

• Multi-language support - English and Arabic with RTL support (add more languages!)
• Collapsible sidebar - Maximize your workspace
• Flexible time periods - View data by day, week, or month
• Tracking controls - Adjust intervals, idle thresholds, and blacklists
• Auto-start on login - Launch automatically when you boot your system
• Custom themes - Personalize your experience

🔒 Privacy & Security

• Local-first - All data stays on your device
• No cloud sync - No data sent to external servers
• Data export - Full control over your data
• Optional crash reporting - Privacy-focused error tracking with PII filtering (learn more)

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/yourusername/lume.git
cd lume

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build
npm run package

Configuration (Optional)

cp .env.example .env
# Add your Sentry DSN for crash reporting

🔧 Development

Tech Stack

• Frontend: React 19, TypeScript, Tailwind CSS v4
• Backend: Electron, Node.js
• Database: SQLite with better-sqlite3 (Repository pattern)
• Build: Vite, electron-builder
• Testing: Jest, React Testing Library
• i18n: react-i18next
• Monitoring: Sentry (optional)

Project Structure

lume/
├── src/
│   ├── main/              # Electron main process
│   ├── renderer/          # React frontend
│   ├── components/        # React components
│   ├── services/          # Business logic services
│   ├── database/          # Database layer (repositories, analytics)
│   └── types/             # TypeScript definitions
├── dist/                  # Built application
└── assets/               # Static assets

Available Scripts

• npm run dev - Start development environment
• npm run build - Build for production
• npm run test - Run tests
• npm run lint - Lint code
• npm run package - Package for distribution

Platform Support

Platform	Status	Notes
macOS	✅ Full support	Requires accessibility permissions
Windows	✅ Full support	PowerShell execution required
Linux	✅ Full support	X11 environment required

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Translation Contributions

Want to add support for your language? See our Translation Guide!

Currently supported:

• 🇬🇧 English
• 🇸🇦 Arabic (العربية)

Help wanted:

• French, Spanish, German, and more!

Quick Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📋 Roadmap

• Cloud sync (optional)
• Mobile companion app
• Plugin system
• Team collaboration features
• AI-powered productivity recommendations

📄 License

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

🙏 Acknowledgments

• Electron - Desktop app framework
• React - UI library
• Tailwind CSS - CSS framework
• better-sqlite3 - SQLite driver

📞 Support

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue

⭐ Show Your Support

If you find Lume helpful, please consider giving it a star ⭐ on GitHub!

---

Made with ❤️ in Iraq for productivity enthusiasts