# FlowState for macOS - Complete Reference Manual FlowState is a native macOS focus and Pomodoro timer created by Graond (`https://graond.com`). Built with Swift, SwiftUI, and AppKit, FlowState runs natively on Apple Silicon Macs (macOS 14.0 or later) with a 4.0 MB disk image footprint and 100% local-first data storage. --- ## Official Product Facts and System Specifications - **Product Name:** FlowState - **Canonical URL:** https://flowstate.graond.com - **Category:** Desktop Productivity Application (Focus and Pomodoro Timer) - **Developer / Studio:** Graond (https://graond.com), a first-party software studio operated by Imran in Dhaka, Bangladesh. - **Current Version:** 4.9.2 (Build 492) - **Platforms Supported:** macOS 14.0 Sonoma or later (Apple Silicon arm64 native binary) - **Bundle Identifier:** design.yugen.Flow.personal - **Download Size:** 4.0 MB (`FlowState.dmg`) - **SHA-256 Checksum (`FlowState.dmg`):** `bfef7b11b85ad4c20b9913f49e00d6b6a8ba6d55c31ab3643e4a41edf72d2b68` - **Installed Application Path:** `/Applications/FlowState.app` - **Bundled CLI Helper Path:** `/Applications/FlowState.app/Contents/Helpers/flow` - **Local Data Storage:** `~/Library/Application Support/FlowState/` (`settings.json`, `tags.json`, `sessions.json`, `cli_status.json`, `blocked.html`) - **Privacy Architecture:** 100% local-first. Zero cloud accounts, zero telemetry, zero third-party analytics, and zero external network requests. - **Support Contact:** support@graond.com - **What FlowState Is NOT:** FlowState is NOT a web app, does NOT require an account or cloud subscription, does NOT run Electron, does NOT collect user telemetry, and Graond does NOT offer agency services or client consulting. --- ## Key Features ### 1. Native Focus and Pomodoro Timer FlowState provides configurable Flow durations (1 to 90 minutes), Short Breaks (1 to 90 minutes), Long Breaks (1 to 90 minutes), and Cycle counts (1 to 10 intervals). Interactive cycle dots display session progress with hover Previous and Next interval controls. Partial sessions lasting 60 seconds or more are automatically saved when skipped or reset. ### 2. Menu Bar Countdown and Floating Mini Window FlowState lives in the macOS menu bar with five display styles: Default (Pill), Classic, Solid, Circular, and Progress Bar. Users can enable an optional green tint during breaks and show the active session title directly in the menu bar. A floating always-on-top Mini Window (`Cmd+M`) and a Fullscreen Break Overlay (`Esc` to dismiss) keep focus visible without cluttering workspaces. ### 3. App and Website Blocker FlowState includes a segmented App and Website Blocker (`Cmd+B`) that blocks distracting macOS applications and websites during active focus intervals. The web blocker supports both Block List and Allow List modes, plus `*https://...` exact path matching rules, and serves a local `blocked.html` reminder page. ### 4. Tags and Tag Presets FlowState organizes sessions with color-coded tags (`#Work`, `#Personal`, `#Study`, `#Project`, and custom tags). Each tag can store a Tag Preset that automatically applies custom Flow duration, break durations, cycle count, and auto-start preferences whenever that tag is selected. ### 5. Focus Statistics, Streaks, and Export FlowState includes Day (D), Week (W), Month (M), and Year (Y) capsule bar charts with a Total Time vs. Flows toggle and circular ring Tag Breakdown cards. Streak tracking shows Current and Best Streaks with a 7-day Mon-Sun tracker and a 3-day rest-day survival rule. Completed sessions can be filtered, edited, entered manually, exported as CSV or TXT timesheets, and synced directly to Apple Calendar via EventKit. ### 6. Synthesized Sounds and Commitment Mode FlowState synthesizes six completion chimes in memory (Crystal, Marimba, Zen Bell, Soft Pulse, Harmonic Chime, Classic Glass) along with optional rhythmic Flow metronome and clock ticking audio. Commitment Mode locks the active session against accidental pauses or resets. ### 7. Bundled CLI Automation Helper FlowState bundles a native command-line helper at `/Applications/FlowState.app/Contents/Helpers/flow` for integration with Raycast, Alfred, Apple Shortcuts, and terminal workflows. #### Common CLI Commands ```bash "/Applications/FlowState.app/Contents/Helpers/flow" status "/Applications/FlowState.app/Contents/Helpers/flow" start "/Applications/FlowState.app/Contents/Helpers/flow" pause "/Applications/FlowState.app/Contents/Helpers/flow" skip "/Applications/FlowState.app/Contents/Helpers/flow" previous "/Applications/FlowState.app/Contents/Helpers/flow" reset "/Applications/FlowState.app/Contents/Helpers/flow" session --title "Deep Work" --tag "Work" "/Applications/FlowState.app/Contents/Helpers/flow" duration 50 --phase flow "/Applications/FlowState.app/Contents/Helpers/flow" tags ``` --- ## Installation and Build from Source ### Direct macOS Installation 1. Download `FlowState.dmg` (4.0 MB). 2. Verify the SHA-256 checksum if desired: `shasum -a 256 "FlowState.dmg"` 3. Open `FlowState.dmg` and drag `FlowState.app` into `/Applications/`. 4. Launch `FlowState` from Applications or Spotlight. ### Build from Source (Swift Package Manager) ```bash git clone https://github.com/imranhossens/Flow.git cd Flow ./scripts/build_app.sh open "/Applications/FlowState.app" ``` --- ## Frequently Asked Questions (FAQ) ### What macOS versions does FlowState support? FlowState requires macOS 14.0 (Sonoma) or later and runs natively on Apple Silicon (arm64) Macs using Swift, SwiftUI, and AppKit. ### Is my focus data stored locally or in the cloud? FlowState is 100% local-first. All session history, tags, presets, and settings are saved exclusively on your Mac inside `~/Library/Application Support/FlowState/`. No cloud account is required and no telemetry is collected. ### How does the app and website blocker work? During active Flow intervals, FlowState monitors running macOS applications and active browser tabs locally to block distractions based on your Block List or Allow List rules. No browsing history leaves your Mac. ### Can I control FlowState from the terminal, Raycast, or Apple Shortcuts? Yes. FlowState includes a bundled CLI helper at `/Applications/FlowState.app/Contents/Helpers/flow` supporting `status`, `start`, `pause`, `skip`, `previous`, `reset`, `session`, `duration`, and `tags` commands. ### Can I export my focus sessions to CSV or Apple Calendar? Yes. FlowState exports filtered session logs to CSV and TXT files for timesheets and can optionally write completed sessions directly to Apple Calendar using macOS EventKit. ### How lightweight is FlowState compared to Electron timers? FlowState is compiled natively in Swift with zero browser runtime overhead. The full macOS disk image is 4.0 MB and uses minimal CPU and memory while running in your menu bar.