Smart scheduling for productive days
SessionFlow is a native macOS app that helps you plan, execute, and reflect on productive days. It automatically schedules work, side, and deep sessions around your existing calendar events, tracks them in real time with ambient sounds and progress indicators, and captures feedback so you can see how your time actually felt.
- 🧠 Smart Scheduling: Automatically fits work, side, and deep sessions into available gaps in your macOS Calendar
- 🔄 Dynamic Patterns: Choose from multiple scheduling patterns (Alternating, All Work First, All Side First, Custom Ratio)
- 💾 Preset Management: Save and quickly switch between configurations for Workdays, Focus Days, Weekends, or any custom mix
- 📅 Calendar Integration: Read from and write directly to macOS Calendar with per-calendar filtering and replacement controls
- ⚙️ Customizable Sessions: Configure names, durations, and target calendars for each session type (Work, Side, Planning, Deep Work)
- 🎯 Hashtag System: Add
#work,#side,#deep,#plan, or#breakto event notes so existing sessions are recognized automatically
- 📊 Interactive Timeline: Drag-and-drop events, resize sessions, lock layout, and freeze projections for manual fine-tuning
- 👁 Session Awareness: Tracks active calendar events—both tagged sessions and your regular calendar events—with ambient sounds, a progress bar, and gentle reminders as sessions approach their end. A progress donut on the dock icon and an optional menu-bar timer let you glance at remaining time without switching windows
- 🪟 Mini-Player: Compact floating window that shows session status at a glance—collapse the main window and keep awareness in a small footprint. Displays idle, next-up, active, and feedback states with the same progress and time info as the full panel
- ⌘ Shortcuts Integration: Trigger macOS Shortcuts when sessions start, end, or approach. Each shortcut receives structured JSON with session details—use it to toggle Focus modes, send notifications, control smart home devices, or anything Shortcuts can do. Template shortcuts are available for every trigger
- 🌙 Night-Owl Mode: Schedule beyond midnight with +1d markers on the timeline (up to 6 am next day)
- ↩️ Undo/Redo: Full history for event moves and projected session edits
- 📈 Productivity Tracking: After each session ends you get a quick feedback prompt (rocket/completed/partial/skipped). A daily productivity card and monthly calendar view summarize your ratings, highlight unrated blocks, and compute weighted focus time so you can see how each day and month actually felt
- 🌑 Beautiful UI: Dark-themed glassmorphic design with intuitive controls
- 🔃 Auto-Updates: Automatic update checks with self-install from GitHub Releases, plus a What's New changelog viewer
Timeline, projections, and controls share a single glass panel so you can see inputs and outputs together.
Sessions flow around existing events instantly as you tweak durations or presets. You can also drag and drop events to change their time and duration.
Workday, Focus, Weekend, or any custom preset stays one click away.
Summary cards highlight real events, projected work, and when you are supposed to be free.
The bottom panel tracks your current session in real time—whether it’s a tagged event (#work, #side, #deep, #plan, #break) or any regular calendar event—displaying elapsed time, a progress bar, and remaining time. Ambient sounds and visual cues keep you in flow, with gentle alerts as the session nears its end. Progress also appears as a donut overlay on the dock icon and as a live timer in the menu bar, so you always know where you stand without switching windows. When a session ends, a quick prompt lets you rate how it went. For a more compact experience, the floating Mini-Player provides the same awareness in a small footprint. You can expand back to the full app anytime.
The right side of the window can show a Productivity card once you start leaving feedback on sessions. It aggregates how many rocket/completed/partial/skipped blocks you had today, how many are still unrated, and computes a weighted Focus Time score based on both duration and rating. From there, a calendar button opens a monthly productivity view with a compact calendar: each day shows colored dots for rated sessions and a tiny focus-time label, making it easy to spot your strongest days and streaks at a glance.
- Download the latest
SessionFlow-vX.X.dmgfrom Releases - Open the DMG file
- Drag
SessionFlow.appto your Applications folder - Launch from Applications or Spotlight
- Grant Calendar permissions when prompted
See Building from Source section below.
- Launch the app, grant Calendar access, and pick your calendars.
- Set target counts and durations for Work, Side, Deep, and Planning sessions.
- Pick a scheduling pattern or load a preset, then review the timeline.
- Press Schedule Sessions when the layout looks right.
- As sessions begin, the bottom panel (or Mini-Player) tracks your progress with ambient sounds, a dock icon donut, and an optional menu-bar timer. Rate each session when it ends to build your productivity history.
- Local Only: Scheduling logic, presets, and state live entirely on your Mac—no accounts, telemetry, or remote services.
- Privacy Respected: Calendar access is limited to the calendars you explicitly pick, and the data never leaves the device.
- User Confirmation: The app only modifies your calendar when you explicitly schedule sessions or drag events — you're always in control.
- Hashtags: Add
#work,#side,#deep,#plan, or#breakto event notes so existing sessions are detected automatically. - Visual Language: Solid borders mark real events; dashed borders with diagonal stripes are projections.
- Presets: Save Workday, Focus, Weekend, or any custom mix for instant reuse.
- Awareness Mode: Toggle “Aware of existing tasks” when you want counts to respect what’s already booked.
- Track Other Events: Enable “Awareness of your other calendar events” to also track regular (untagged) calendar events with timer, progress, and ambient sound.
- Shortcuts: Set up macOS Shortcuts to automate actions at session boundaries. Go to Settings → Shortcuts, enable a trigger, and name your shortcut. Download ready-made templates to get started instantly.
- Dock & Menu Bar: Enable the dock progress donut and menu-bar timer in Session Awareness settings so you can monitor remaining time from anywhere.
- Mini-Player: Click the collapse button on the bottom panel to detach a floating mini-player; expand back anytime.
- Freeze & Adjust: After scheduling, freeze projections and drag/resize them by hand for pixel-perfect layouts.
- Copy Events: Right-click any timeline event and use “Copy to...” to duplicate it to a nearby day.
- Lock Dragging: Toggle the lock icon to prevent accidental event moves while reviewing your schedule.
- Night Scheduling: Extend the schedule end hour past midnight to plan late-night sessions with clear +1d markers.
- Rate Sessions: After each session ends, use the quick feedback prompt to rate it—these ratings feed into the Productivity card and monthly view.
The project follows a modular architecture with clear separation of concerns:
SessionFlow/
├── Models/
│ ├── Session.swift
│ ├── Preset.swift
│ ├── SchedulePattern.swift
│ ├── SessionAwarenessConfig.swift
│ └── SessionFeedback.swift
│
├── Services/
│ ├── SchedulingEngine.swift
│ ├── CalendarService.swift
│ ├── AvailabilityCalculator.swift
│ ├── EventUndoManager.swift
│ ├── SessionAwarenessService.swift
│ ├── SessionAudioService.swift
│ ├── DockProgressController.swift
│ ├── MenuBarController.swift
│ └── UpdateService.swift
│
└── Views/
├── ContentView.swift
├── TimelineView.swift
├── SettingsPanel.swift
├── PresetManager.swift
├── SessionAwarenessPanel.swift
├── MiniPlayerView.swift
├── ProductivityCard.swift
├── WhatsNewView.swift
├── AboutView.swift
└── [other views...]
Session.swift: DefinesSessionTypeenum (Work, Side, Deep, Planning) andScheduledSessiondata structurePreset.swift: Handles preset configuration and persistence viaUserDefaultsSchedulePattern.swift: Generates session orders based on patterns (Alternating, All Work First, etc.)SessionAwarenessConfig.swift: Configuration for session tracking, sounds, dock progress, and menu-bar timerSessionFeedback.swift:SessionRatingenum and feedback storage via calendar event notes
SchedulingEngine.swift: Core scheduling algorithm that fits sessions into available time gapsCalendarService.swift: EventKit wrapper for reading/writing calendar events with per-calendar filteringAvailabilityCalculator.swift: Identifies free time slots between existing eventsEventUndoManager.swift: Custom undo/redo stack for calendar event and projected session changesSessionAwarenessService.swift: Tracks active and upcoming sessions, manages progress, and triggers feedback promptsSessionAudioService.swift: Ambient sound playback, transition sounds, and accelerando during sessionsDockProgressController.swift: Renders the progress donut overlay on the dock iconMenuBarController.swift: Manages the optional menu-bar status item with live timer
ContentView.swift: Main layout container and state managementTimelineView.swift: Interactive timeline with drag-and-drop, resize, locking, and freeze mode for both events and projected sessionsSettingsPanel.swift: Configuration controls (session counts, durations, patterns)PresetManager.swift: Preset saving, loading, and management UISessionAwarenessPanel.swift: Bottom panel showing active session, next-up, and feedback statesMiniPlayerView.swift: Compact floating window mirroring the awareness panelProductivityCard.swift: Daily summary and monthly calendar view of session feedbackWhatsNewView.swift: Fetches and displays the changelog from GitHub after updatesAboutView.swift: About window with version and build info
- Update
SessionTypeenum inSession.swiftwith a new case, icon, and color - Update
SchedulingEngine.swiftto handle the new type in its generation loop - Add UI controls in
SettingsPanel.swiftfor configuration - Update preset system in
Preset.swiftto include new type - Add hashtag support in
CalendarService.swiftif needed
- Core algorithm:
SchedulingEngine.generateSchedule() - Gap detection:
AvailabilityCalculator.calculate() - Pattern logic:
SchedulePatternenum andSessionOrderGenerator.generateOrder() - Existing task awareness: Hashtag parsing in
CalendarService.swift
IMPORTANT: When adding new Swift files, you must manually update SessionFlow.xcodeproj/project.pbxproj:
PBXBuildFilesectionPBXFileReferencesectionPBXGroupsectionPBXSourcesBuildPhasesection
See Agents.md for detailed instructions.
- macOS: 13.0 (Ventura) or later
- Processor: Apple Silicon (M1/M2/M3) or Intel
- Permissions: Calendar access (requested on first launch)
- SwiftUI: Main UI framework
- EventKit: macOS Calendar integration
- Foundation: Core logic and date handling
No external dependencies or package managers required!
- Xcode 15.0 or later
- macOS 13.0 or later
- Git
- Apple Developer Team ID (update the
TEAM_ID="RGFAX8X946"placeholder inbuild_app.shandSessionFlow.xcodeproj/project.pbxprojto your own Team ID before running the build scripts)
# Clone the repository
git clone https://github.com/kibermaks/SessionFlow.git
cd SessionFlow
# Build using the build script (creates Release build)
./build_app.sh
# Or open in Xcode
open SessionFlow.xcodeprojThe project includes several convenience scripts:
Builds a Release version of the app with version management.
⚠️ Before running, update theTEAM_ID="RGFAX8X946"placeholder in bothbuild_app.shandSessionFlow.xcodeproj/project.pbxprojso the script can sign with your Apple Developer account.
# Increment build number only (default)
./build_app.sh
# Bump minor version (1.0 → 1.1)
./build_app.sh minor
# Bump major version (1.0 → 2.0)
./build_app.sh major
# Set specific version
./build_app.sh version 1.5What it does:
- Updates version numbers in project file
- Builds Release configuration
- Signs the app (if certificates available)
- Outputs to
./build_output/ - Copies app to current directory
- Launches the built app
Creates a distributable DMG file for the app.
# Create DMG from built app
./create_dmg.shWhat it does:
- Packages the app into a DMG
- Creates Applications folder symlink
- Adds README with installation instructions
- Outputs to
./dmg_output/ - Names file as
SessionFlow-vX.Y.dmg
# 1. Make your changes in Xcode
open SessionFlow.xcodeproj
# 2. Build and test locally
./build_app.sh
# 3. When ready to release, create DMG
./create_dmg.sh- Quick Start Guide
- Usage Tips
- FAQ (coming soon)
- Architecture & Key Elements
- Contributing Guidelines
- Code Signing Setup - Secure signing for public repos
- Agent Knowledge Base - READ THIS FIRST before making changes
- Changelog
We welcome contributions! Please see CONTRIBUTING.md for details on:
- Setting up your development environment
- Code style and standards
- Submitting pull requests
- Reporting issues
- Feature requests
Future features and improvements:
- Multi-day scheduling
- Recurring session templates
- iCloud sync for presets
- Custom session colors and icons
- Calendar widget support
Check the Issues page for current known issues and feature requests.
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with SwiftUI by Apple
- Calendar integration powered by EventKit
- Inspired by the need for better task scheduling and time management
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- GitHub User: @kibermaks (for security issues only)
If you find this project useful, please consider giving it a star!
Made with ❤️ for productive Mac users