{"id":35207175,"url":"https://github.com/saranshbarua/flumen","last_synced_at":"2026-03-04T19:04:20.387Z","repository":{"id":330939436,"uuid":"1123283733","full_name":"saranshbarua/pomodoro","owner":"saranshbarua","description":"Completely free Pomodoro timer with task management and reports for macos","archived":false,"fork":false,"pushed_at":"2026-01-29T03:32:10.000Z","size":8268,"stargazers_count":4,"open_issues_count":7,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-29T08:33:29.597Z","etag":null,"topics":["macos","pomodoro","pomodoro-timer","task-management"],"latest_commit_sha":null,"homepage":"https://saranshbarua.github.io/pomodoro/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saranshbarua.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-26T14:53:25.000Z","updated_at":"2026-01-29T03:50:57.000Z","dependencies_parsed_at":"2026-01-01T11:01:50.821Z","dependency_job_id":null,"html_url":"https://github.com/saranshbarua/pomodoro","commit_stats":null,"previous_names":["saranshbarua/pomodoro"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/saranshbarua/pomodoro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saranshbarua%2Fpomodoro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saranshbarua%2Fpomodoro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saranshbarua%2Fpomodoro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saranshbarua%2Fpomodoro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saranshbarua","download_url":"https://codeload.github.com/saranshbarua/pomodoro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saranshbarua%2Fpomodoro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29113190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T03:44:17.043Z","status":"ssl_error","status_checked_at":"2026-02-05T03:44:12.077Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["macos","pomodoro","pomodoro-timer","task-management"],"created_at":"2025-12-29T15:21:08.478Z","updated_at":"2026-03-04T19:04:20.375Z","avatar_url":"https://github.com/saranshbarua.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌊 Flumen for macOS\n\n![Status](https://img.shields.io/badge/status-stable-green)\n![Platform](https://img.shields.io/badge/platform-macOS-lightgrey)\n![License](https://img.shields.io/badge/license-Non--Commercial-red)\n\nA 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.\n\n![Flumen for macOS](docs/assets/banner.png)\n\n---\n\n## 💾 Download\n\n### [Download Latest Release (.zip)](https://github.com/saranshbarua/flumen/releases/latest/download/Flumen_macOS_Universal.zip)\n\nTo install and run the app:\n1. Download the `Flumen_macOS_Universal.zip` from the link above.\n2. Unzip the file to your **Applications** folder.\n3. **Right-click** `Flumen.app` and select **Open**.\n4. Click **Open** again in the security dialog (this is required for the first launch as the app is currently ad-hoc signed).\n\n\u003e [!TIP]\n\u003e **If macOS blocks the app or asks to move it to the Bin:**\n\u003e 1. Open **System Settings** \u003e **Privacy \u0026 Security**.\n\u003e 2. Scroll down to the **Security** section.\n\u003e 3. You will see a message: *\"Flumen.app was blocked from use because it is not from an identified developer.\"*\n\u003e 4. Click **Open Anyway** and enter your password if prompted.\n\n---\n\n## ✨ Features\n\n### 🍏 Native macOS Presence\n- **Menu Bar Companion**: Mirror your remaining time directly in the macOS menu bar for glanceable tracking.\n- **Floating Popup**: Popover-style interface that stays on top when you need it without stealing focus.\n- **Global Shortcuts**: Toggle visibility from anywhere with `⌥⇧P` (Option+Shift+P).\n- **Space-Aware**: The timer follows you across Mission Control spaces automatically.\n\n### 📊 Integrated Analytics \u0026 Tasks\n- **Task Focused**: A slide-up \"Task Shelf\" to manage your session goals without distraction.\n- **Project Tagging**: Categorize your focus sessions with project-level tags to see where your time goes.\n- **Deep Insights**: Detailed bar charts, project distribution lists, and streak tracking.\n- **CSV Export**: Export your focus data to CSV for external analysis.\n- **Native Persistence**: Your logs and tasks are saved to a native SQLite database, surviving updates and restarts.\n- **Automatic Logging**: Focus time is logged automatically every minute and on session completion.\n\n---\n\n## 📸 Visual Showcase\n\n| Focus Mode | Task Shelf | Reports \u0026 Insights |\n| :---: | :---: | :---: |\n| ![Main Timer](docs/assets/main-timer.png) | ![Task Shelf](docs/assets/task-shelf.png) | ![Reports](docs/assets/analytics-report-1.png) |\n\n| Long Break | Short Break | Settings |\n| :---: | :---: | :---: |\n| ![Long Break](docs/assets/long-break.png) | ![Short Break](docs/assets/short-break.png) | ![Settings](docs/assets/settings.png) |\n\n---\n\n## 🛠 Tech Stack\n\n- **Frontend**: [React 19](https://react.dev/), [TypeScript](https://www.typescriptlang.org/), [Zustand](https://github.com/pmndrs/zustand), [Recharts](https://recharts.org/).\n- **Native Wrapper**: [Swift](https://developer.apple.com/swift/), AppKit, WKWebView.\n- **Communication**: Custom JS-to-Swift bridge using `WKScriptMessageHandler`.\n- **Testing**: [Vitest](https://vitest.dev/), React Testing Library.\n\n---\n\n## 🏗 Build from Source\n\n### Prerequisites\n- macOS 13+ (Ventura or later)\n- [Node.js](https://nodejs.org/) \u0026 npm\n- Xcode Command Line Tools (`xcode-select --install`)\n\n### Development Steps\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/saranshbarua/flumen.git\n   cd flumen\n   ```\n2. **Install Dependencies**:\n   ```bash\n   npm install\n   ```\n3. **Build the Universal Binary**:\n   ```bash\n   sh build_app.sh\n   ```\n   This will generate `Flumen.app` and a distribution ZIP in the project root.\n\n---\n\n## 📖 Documentation\n\nExplore the technical details:\n- 🗺️ [Roadmap](docs/ROADMAP.md) - Future features and improvements.\n- 🏗️ [Architecture](docs/CODEBASE.md) - Deep dive into the hybrid bridge.\n- ✨ [Full Feature List](docs/FEATURES.md) - Detailed breakdown of capabilities.\n- 🧪 [Testing Strategy](docs/TESTING.md) - Our approach to quality.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Whether you're fixing a bug, suggesting a feature, or improving documentation, we appreciate your help. Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for:\n- **Conventional Commits**: We follow strict commit naming conventions.\n- **Development Workflow**: How to set up and run the project locally.\n- **Testing**: How to run our Vitest suite.\n- **Release Process**: How we automate builds and deployments.\n\n## 📄 License\n\nThis 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](LICENSE) file for the full legal text.\n\n---\n\nBuilt with ❤️ for deep thinkers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaranshbarua%2Fflumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaranshbarua%2Fflumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaranshbarua%2Fflumen/lists"}