Focus Sessions

A native macOS productivity app for tracking work in 15‑minute blocks, with an AI day‑planner and focus‑mode (Do Not Disturb).

Run a 15‑minute timer; when it completes, attribute the block to a folder → project → task and note what you accomplished. Your sessions feed analytics (category breakdown, most‑productive hour, daily/weekly views) and a timeline. An AI assistant can build and refine a time‑blocked day plan in a streaming chat, and the plan overlays your real timeline so you can see intention vs. reality.

Features

• 15‑minute focus timer with a circular/segmented progress display and a compact ambient mode.
• Session attribution to a customizable folder → project → task hierarchy.
• Analytics: today / week / month timelines, category breakdown, most‑productive hour, and an hourly heatmap.
• AI day‑planner (chat): describe your fixed commitments and what you want to get done; the assistant streams a plan, explains its choices, and you refine it conversationally. Natural‑language dates ("tomorrow") are honored. Conversations are saved per day.
  • Provider‑agnostic: ships with Claude (Anthropic) and DeepSeek; pick one in Settings.
• Plan overlays the timeline: planned blocks appear as a faint "intended" layer behind your real logged sessions.
• Do Not Disturb: silences the app's own sounds during a focus block, and can optionally trigger a macOS Focus via a user‑configured Shortcut.
• History & export: browse past days; import/export sessions as CSV.

Requirements

• macOS 13+
• Xcode 15+ (Swift / SwiftUI + AppKit)

Build & run

Open the project in Xcode and run:

open FocusSessions/FocusSessions.xcodeproj

Or from the command line:

xcodebuild -project FocusSessions/FocusSessions.xcodeproj -scheme FocusSessions -configuration Release build

Note: the Debug build seeds sample sessions on launch (#if DEBUG). Use the Release build for real use.

AI setup

The AI day‑planner needs an API key for your chosen provider:

1. Open Settings (gear in the header).
2. Pick a provider — Claude (get a key) or DeepSeek (get a key).
3. Paste the key and Save. Keys are stored in the macOS Keychain (one per provider), never in plain settings.

Distribution note

The app is not sandboxed (it makes network calls to the AI provider and can trigger Shortcuts). It is intended for direct distribution, not the Mac App Store.

Architecture

See CLAUDE.md for a detailed architecture guide (data model, persistence, the AI/DND subsystems, and conventions).

License

MIT