SessionFlow

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.

Download Latest Release • Documentation • Contributing

---

✨ Key Features

Plan

• 🧠 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 #break to event notes so existing sessions are recognized automatically

Execute

• 📊 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
• 🔒 Commit Mode: A strict focus mode for selected SessionFlow tasks. When a session starts, it can block every display until you name what you intend to do; when the session ends, it can block again until you rate and review how it went. Useful when you benefit from extra structure, friction, and explicit intent before starting work
• 🪟 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
• 🤖 AI Control (MCP): Optional local MCP server so trusted agents can inspect the schedule, edit task/config inputs, rebuild previews, and commit tagged sessions with your token
• ⌘ 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

Reflect

• 📈 Focus & Alignment Tracking: After each session ends, rate both how focused the work was and how well it served your current goal. The right panel computes Focus Time, Aligned Focus, Alignment %, and a daily diagnosis phrase so you can tell the difference between “I worked hard” and “I worked on the right thing”

Polish

• 🌑 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

🖼 Visual Walkthrough

Welcome Guide

Command Center

Timeline, projections, and controls share a single glass panel so you can see inputs and outputs together.

Dynamic Scheduling + Drag & Drop

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.

Preset Library

Workday, Focus, Weekend, or any custom preset stays one click away.

Availability Insights

Summary cards highlight real events, projected work, and when you are supposed to be free.

Session Awareness & Mini-Player

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.

Commit Mode

Commit Mode is the intentionally strict version of starting a session. Enable it from the main window, choose which SessionFlow task types it applies to, and the app can cover every display when a scheduled task begins. Before you continue, you must write the goal or goals for that session, so the first action is deciding what the block is actually for.

At the end of the session, Commit Mode can block again until you rate the session and optionally write review notes. Those goals and reflections are saved back into the calendar event, and the active goals can stay visible in the bottom panel or Mini-Player while you work. It is designed for people who need stronger external structure, including users with ADHD-style focus challenges, without making every Session Awareness feature mandatory.

Focus & Alignment Tracking

The right side of the window can show a Focus & Alignment card once you start reviewing ended sessions. The first question is about Focus: how well you executed the block. The second question is about Alignment: whether that focused time moved the goal that matters right now.

This separation is intentional. You can have a day that was productive in the ordinary sense, but still misaligned because the work drifted into maintenance, tooling, or side projects. SessionFlow keeps those signals separate so the review is more honest.

Focus uses the quick end-of-session ratings:

Focus rating	Meaning	Default weight
Fire	Excellent session	100%
Done	Completed with solid focus	80%
Partly	Some focus, some drift	50%
Procrastinated	You were present, but lost the block to distraction	0%
Skipped	Did not meaningfully happen	0%

Alignment uses a separate five-level scale:

Alignment	Meaning	Weight
Off-track	Pulled away from the current goal	0%
Maintenance	Necessary upkeep, weak goal movement	25%
Support	Indirect setup, tooling, preparation, or learning	50%
Strategic	Important progress, not direct payoff yet	75%
Direct	Directly moved the current goal	100%

The core stats are time-weighted:

Spent Time = duration of reviewed sessions that actually happened
Focus Time = session duration × Focus weight
Aligned Focus = Focus Time × Alignment weight
Alignment % = Aligned Focus / alignment-eligible spent time

For example, a 2-hour session rated Done and Support gives 96 minutes of Focus Time and 48 minutes of Aligned Focus. That means the work was real, but only half of that focused effort served the current goal.

For Fire, Done, and Partly, alignment-eligible spent time is the focus-weighted duration. A session rated Procrastinated adds 0 minutes of Focus Time, but its full duration counts in Alignment %. Skipped stays neutral because the session effectively did not happen.

External calendar events without an Alignment tag are not included in the Alignment % denominator, so personal or non-work commitments can still be reviewed without lowering the directional score.

The daily card also shows a short diagnosis phrase. It is generated from the combination of Focus Time and Alignment %, so it can call out patterns such as “productive, but poorly aligned” or “high-quality effort landed where it mattered.” A setting in Awareness preferences lets you turn this phrase on or off.

The calendar button opens a monthly Focus & Alignment view. Each day shows Focus ratings, Focus Time, and Alignment %. Monthly and yearly summaries include Focus Time, Aligned Focus, Alignment %, and counts across the Alignment scale, making it easier to spot weeks where effort was high but direction was weak.

🚀 Installation

Option 1: Download Pre-built Release (Recommended)

1. Download the latest SessionFlow-YYYY.M.D.dmg from Releases
2. Open the DMG file
3. Drag SessionFlow.app to your Applications folder
4. Launch from Applications or Spotlight
5. Grant Calendar permissions when prompted

Option 2: Build from Source

See Building from Source section below.

🎯 Quick Start

1. Launch the app, grant Calendar access, and pick your calendars.
2. Set target counts and durations for Work, Side, Deep, and Planning sessions.
3. Pick a scheduling pattern or load a preset, then review the timeline.
4. Press Schedule Sessions when the layout looks right.
5. 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. When a session ends, rate Focus first, then Alignment, to build a history of both execution quality and goal fit.

🔒 Privacy & Local Processing

• 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.

💡 Usage Tips

• Hashtags: Add #work, #side, #deep, #plan, or #break to 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.
• Commit Mode: Use the shield control next to Settings to turn strict session gates on or off. The adjacent settings button opens task filters, goal requirements, end-review requirements, blocker templates, and how prominently goals appear during the session.
• AI Control (MCP): Go to Settings → General → AI Control (MCP), enable the server, then copy the endpoint, token, or Claude Code setup command from the app.
• 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, rate Focus first and Alignment second. Focus says whether the session happened well; Alignment says whether it served the current goal. These ratings feed the Focus & Alignment card and monthly view.

⚡ Power Features

These are the tricks that make SessionFlow click once you know them.

Keyboard Shortcuts

Shortcut	What it does
⌘Z	Undo the last drag, resize, or delete on the timeline
⇧⌘Z	Redo
Esc	Cancel an active drag, close the detail sheet, or dismiss the event creation popover
Hold ⇧ (Shift) while dragging	Free-form positioning — skips the 5-minute grid
Hold ⌥ (Option) while resizing	Snap to 5-minute increments for fine control

Timeline Tricks

• Double-click empty space (left half) to create a new event right there — no need to open Calendar.app. An autocomplete dropdown suggests recent events so you can recreate them in two keystrokes.
• Double-click an event block to open its detail sheet where you can edit the title, notes, and URL inline. Enter saves notes; Shift+Enter inserts a newline.
• Drag the top or bottom edge of any event or projected session to resize it. The grab zone is about 8 pixels from the edge.
• Right-click any calendar event to copy it to an upcoming day or pick a custom date. Great for repeating a meeting you just had.
• Right-click a projected session to schedule it immediately, schedule everything up to that point ("Schedule All Up to Here"), or rename it.

Event Creation Popover

When the popover is open after a double-click:

• Type a few letters and recent events matching your input appear instantly with their calendar and duration pre-filled. Hit Tab to accept.
• ⌘↑ / ⌘↓ cycles through your calendars without touching the mouse.
• ↑ / ↓ navigates suggestions; Tab or click applies one.

Freeze & Manual Layout

Drag any projected session and the app automatically freezes all projections so they stop recalculating. Now you can rearrange sessions by hand — overlapping sessions push out of the way automatically. Unfreeze when you want the engine to take over again.

Awareness Anywhere

You don't need the main window open to stay on track:

• Dock icon shows a progress donut for the active session.
• Menu bar shows a live countdown timer.
• Mini-player floats on your desktop — collapse the bottom awareness panel to switch to it.
• Mute button is always accessible from the mini-player and the bottom panel.
• Mic-aware auto-mute silences ambient sounds automatically when your microphone is active — no need to manually mute before a call or recording.

Commit Mode

Commit Mode is for sessions where you do not want to drift into work on autopilot. It is independent from Session Awareness: the app only needs to be running, and Commit Mode will watch your selected tagged SessionFlow tasks. When a matching task starts, a blocker appears on all displays and asks for one or more goals. Only one display shows the active form, so you can move focus between monitors without creating duplicate answers.

The end gate is just as deliberate: require a rating, require a written review, or keep one of them optional. The point is to force a clean boundary around the session: decide the target, do the work, then leave a trace of how it actually went.

Sounds & Accelerando

Each session type can have its own ambient sound, and the app can gradually speed it up as the session nears its end — like a musical accelerando. The effect is subtle at first and builds toward the finish, giving you a natural sense of time pressure without needing to glance at a clock. You control the max speed multiplier per session type in Settings → Awareness.

You can also import your own sound files — drop any audio file into the sound picker in Awareness settings and it becomes available for any session type.

Shortcuts Automation

Each trigger (session start, end, approaching, rest boundaries) sends a structured JSON payload to your macOS Shortcut. You can use this to toggle Focus modes, send yourself a Slack message, control smart lights, or anything else Shortcuts supports — the app doesn't care what you do with the data.

AI Control (MCP)

SessionFlow can expose a token-protected local MCP endpoint for trusted agents such as Claude Code or Claude Desktop. The server is off by default, binds to loopback only, and starts automatically on app launch after you enable it.

1. Open SessionFlow.
2. Go to Settings → General → AI Control (MCP).
3. Toggle Enable MCP server.
4. Copy the endpoint and token shown in the app. The default endpoint is http://127.0.0.1:8787/mcp, but the active port shown in Settings is the source of truth.

Claude Code setup:

claude mcp add --transport http sessionflow http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"

Claude Desktop can connect through mcp-remote:

{
  "mcpServers": {
    "sessionflow": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:<port>/mcp",
        "--header",
        "Authorization:Bearer <token>"
      ]
    }
  }
}

After connecting, call the learn tool first. It returns the bundled SessionFlow agent guide with the scheduling concepts, tool list, argument shapes, examples, and safety rules. Agents can also read the sessionflow://guide MCP resource. The source copy lives at SessionFlow/Resources/MCP/AgentGuide.md.

🏗 Architecture & Key Elements

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
│   └── MCP/
│       ├── MCPServerController.swift
│       ├── MCPHTTPListener.swift
│       ├── MCPTools.swift
│       └── ScheduleCoordinator.swift
│
├── Resources/
│   └── MCP/
│       └── AgentGuide.md
│
└── Views/
    ├── ContentView.swift
    ├── TimelineView.swift
    ├── SettingsPanel.swift
    ├── PresetManager.swift
    ├── SessionAwarenessPanel.swift
    ├── MiniPlayerView.swift
    ├── ProductivityCard.swift
    ├── WhatsNewView.swift
    ├── AboutView.swift
    └── [other views...]

Key Components

Models

• Session.swift: Defines SessionType enum (Work, Side, Deep, Planning) and ScheduledSession data structure
• Preset.swift: Handles preset configuration and persistence via UserDefaults
• SchedulePattern.swift: Generates session orders based on patterns (Alternating, All Work First, etc.)
• SessionAwarenessConfig.swift: Configuration for session tracking, sounds, dock progress, and menu-bar timer
• SessionFeedback.swift: Focus ratings, Alignment levels, and review storage via calendar event notes

Services

• SchedulingEngine.swift: Core scheduling algorithm that fits sessions into available time gaps
• CalendarService.swift: EventKit wrapper for reading/writing calendar events with per-calendar filtering
• AvailabilityCalculator.swift: Identifies free time slots between existing events
• EventUndoManager.swift: Custom undo/redo stack for calendar event and projected session changes
• SessionAwarenessService.swift: Tracks active and upcoming sessions, manages progress, and triggers Focus & Alignment prompts
• SessionAudioService.swift: Ambient sound playback, transition sounds, and accelerando during sessions
• DockProgressController.swift: Renders the progress donut overlay on the dock icon
• MenuBarController.swift: Manages the optional menu-bar status item with live timer
• MCPServerController.swift: Owns the local MCP server, bearer-token settings, and start/stop state for AI Control
• MCPHTTPListener.swift: Loopback HTTP adapter for the MCP SDK's stateless transport
• MCPTools.swift: Defines the MCP tool catalog, dispatch, and the learn guide/resource
• ScheduleCoordinator.swift: Mirrors schedule preview/commit/delete flows for MCP without going through SwiftUI views

Views

• ContentView.swift: Main layout container and state management
• TimelineView.swift: Interactive timeline with drag-and-drop, resize, locking, and freeze mode for both events and projected sessions
• SettingsPanel.swift: Configuration controls (session counts, durations, patterns)
• PresetManager.swift: Preset saving, loading, and management UI
• SessionAwarenessPanel.swift: Bottom panel showing active session, next-up, and feedback states
• MiniPlayerView.swift: Compact floating window mirroring the awareness panel
• ProductivityCard.swift: Daily and monthly Focus & Alignment summary, including Focus Time, Aligned Focus, Alignment %, and diagnosis phrases
• WhatsNewView.swift: Fetches and displays the changelog from GitHub after updates
• AboutView.swift: About window with version and build info

🔧 Development Guide

Adding a New Session Type

1. Update SessionType enum in Session.swift with a new case, icon, and color
2. Update SchedulingEngine.swift to handle the new type in its generation loop
3. Add UI controls in SettingsPanel.swift for configuration
4. Update preset system in Preset.swift to include new type
5. Add hashtag support in CalendarService.swift if needed

Modifying Scheduling Logic

• Core algorithm: SchedulingEngine.generateSchedule()
• Gap detection: AvailabilityCalculator.calculate()
• Pattern logic: SchedulePattern enum and SessionOrderGenerator.generateOrder()
• Existing task awareness: Hashtag parsing in CalendarService.swift

Modifying MCP Tools

• Tool definitions and dispatch live in SessionFlow/Services/MCP/MCPTools.swift.
• Server startup, port, and token behavior live in SessionFlow/Services/MCP/MCPServerController.swift.
• Calendar-writing operations should go through ScheduleCoordinator and the CalendarWriting protocol so tests can use fakes instead of the real calendar.
• Update SessionFlow/Resources/MCP/AgentGuide.md whenever you add, rename, or materially change a tool. The learn tool and sessionflow://guide resource serve that file to agents.
• Run xcodebuild test -scheme SessionFlow -destination 'platform=macOS' after MCP changes. The SessionFlowTests target covers MCP tools, listener behavior, coordinator behavior, and guide coverage.

Adding New Files

IMPORTANT: When adding new Swift files, you must manually update SessionFlow.xcodeproj/project.pbxproj:

• PBXBuildFile section
• PBXFileReference section
• PBXGroup section
• PBXSourcesBuildPhase section

See Agents.md for detailed instructions.

📦 Requirements & Dependencies

System Requirements

• macOS: 14.0 (Sonoma) or later
• Processor: Apple Silicon (M1/M2/M3) or Intel
• Permissions: Calendar access (requested on first launch)

Dependencies

• SwiftUI: Main UI framework
• EventKit: macOS Calendar integration
• Foundation: Core logic and date handling
• MCP Swift SDK: Official modelcontextprotocol/swift-sdk package, product MCP, for the local AI-control server

Swift Package Manager dependencies are resolved by Xcode and pinned in SessionFlow.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved.

🛠 Building from Source

Prerequisites

• Xcode 26.5 or later (the MCP Swift SDK needs a Swift 6.1-capable toolchain, and the app icon uses the current Icon Composer .icon format)
• macOS 14.0 or later
• Git
• Apple Developer Team ID (update the TEAM_ID="RGFAX8X946" placeholder in build_app.sh and SessionFlow.xcodeproj/project.pbxproj to your own Team ID before running the build scripts)

Clone and Build

# Clone the repository
git clone https://github.com/kibermaks/SessionFlow.git
cd SessionFlow

# Build using the build script (Debug by default)
./build_app.sh

# Build a distribution-style Release app
./build_app.sh --release

# Or open in Xcode
open SessionFlow.xcodeproj

Build Scripts

The project includes several convenience scripts:

./build_app.sh [current|dedicated-version YYYY.M.D] [--release]

Builds the app with date-based version management. By default it builds Debug, copies SessionFlow.app to the repository root, and launches it. Add --release to build Release and copy the app to ./release/.

⚠️ Before running, update the TEAM_ID="RGFAX8X946" placeholder in both build_app.sh and SessionFlow.xcodeproj/project.pbxproj so the script can sign with your Apple Developer account.

# Set marketing version to today's date and increment build number (default)
./build_app.sh

# Keep current marketing version and increment build number only
./build_app.sh current

# Build with a dedicated version
./build_app.sh dedicated-version 2026.4.9

# Build Release instead of Debug
./build_app.sh current --release

What it does:

• Updates version numbers in project file
• Builds Debug by default, or Release with --release
• Signs the app (if certificates available)
• Uses script-local derived data as scratch space, then removes it
• Copies Debug builds to ./SessionFlow.app and Release builds to ./release/SessionFlow.app
• Launches the built app for Debug builds

./create_dmg.sh

Creates a distributable DMG file for the app.

# Create DMG from built app
./create_dmg.sh

What 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-YYYY.M.D.dmg

Development Workflow

# 1. Make your changes in Xcode
open SessionFlow.xcodeproj

# 2. Build and test locally
xcodebuild test -scheme SessionFlow -destination 'platform=macOS'
./build_app.sh current

# 3. When ready to release, create DMG
./create_dmg.sh

📚 Documentation

For Users

• Quick Start Guide
• Usage Tips
• FAQ (coming soon)

For Developers

• Architecture & Key Elements
• Contributing Guidelines
• Code Signing Setup - Secure signing for public repos
• Agent Knowledge Base - READ THIS FIRST before making changes
• Changelog

🤝 Contributing

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

📋 Roadmap

Future features and improvements:

• Multi-day scheduling
• Recurring session templates
• iCloud sync for presets
• Custom session colors and icons
• Calendar widget support

🐛 Known Issues

Check the Issues page for current known issues and feature requests.

📄 License

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

🙏 Acknowledgments

• Built with SwiftUI by Apple
• Calendar integration powered by EventKit
• Inspired by the need for better task scheduling and time management

💬 Community & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• GitHub User: @kibermaks (for security issues only)

⭐ Star History

If you find this project useful, please consider giving it a star!

---

Made with ❤️ for productive Mac users

Report Bug • Request Feature • View Releases