A beautiful, free focus timer for macOS. Lives in your menu bar, stores data locally, and stays out of your way. No bloat, no paywalls, no cloud.
To install and run the app:
- Download the
Flumen_macOS_Universal.zipfrom the link above. - Unzip the file to your Applications folder.
- Right-click
Flumen.appand select Open. - Click Open again in the security dialog (this is required for the first launch as the app is currently ad-hoc signed).
Tip
If macOS blocks the app or asks to move it to the Bin:
- Open System Settings > Privacy & Security.
- Scroll down to the Security section.
- You will see a message: "Flumen.app was blocked from use because it is not from an identified developer."
- Click Open Anyway and enter your password if prompted.
- Menu Bar Companion: Mirror your remaining time directly in the macOS menu bar for glanceable tracking.
- Floating Popup: Popover-style interface that stays on top when you need it without stealing focus.
- Global Shortcuts: Toggle visibility from anywhere with
⌥⇧P(Option+Shift+P). - Space-Aware: The timer follows you across Mission Control spaces automatically.
- Task Focused: A slide-up "Task Shelf" to manage your session goals without distraction.
- Project Tagging: Categorize your focus sessions with project-level tags to see where your time goes.
- Deep Insights: Detailed bar charts, project distribution lists, and streak tracking.
- CSV Export: Export your focus data to CSV for external analysis.
- Native Persistence: Your logs and tasks are saved to a native SQLite database, surviving updates and restarts.
- Automatic Logging: Focus time is logged automatically every minute and on session completion.
| Focus Mode | Task Shelf | Reports & Insights |
|---|---|---|
 |
 |
 |
| Long Break | Short Break | Settings |
|---|---|---|
 |
 |
 |
- Frontend: React 19, TypeScript, Zustand, Recharts.
- Native Wrapper: Swift, AppKit, WKWebView.
- Communication: Custom JS-to-Swift bridge using
WKScriptMessageHandler. - Testing: Vitest, React Testing Library.
- macOS 13+ (Ventura or later)
- Node.js & npm
- Xcode Command Line Tools (
xcode-select --install)
- Clone the repository:
git clone https://github.com/saranshbarua/flumen.git cd flumen - Install Dependencies:
npm install
- Build the Universal Binary:
This will generate
sh build_app.sh
Flumen.appand a distribution ZIP in the project root.
Explore the technical details:
- 🗺️ Roadmap - Future features and improvements.
- 🏗️ Architecture - Deep dive into the hybrid bridge.
- ✨ Full Feature List - Detailed breakdown of capabilities.
- 🧪 Testing Strategy - Our approach to quality.
We welcome contributions! Whether you're fixing a bug, suggesting a feature, or improving documentation, we appreciate your help. Please see our CONTRIBUTING.md for:
- Conventional Commits: We follow strict commit naming conventions.
- Development Workflow: How to set up and run the project locally.
- Testing: How to run our Vitest suite.
- Release Process: How we automate builds and deployments.
This project is licensed under a custom Non-Commercial Share-Alike license. It is free for personal use and internal work productivity, but selling the software or redistributing it for commercial gain is strictly prohibited. Any modifications must also be shared under the same terms. See the LICENSE file for the full legal text.
Built with ❤️ for deep thinkers.
