Building from Source

Why Build from Source?

Building Dayflow from source allows you to:

Audit the code: Inspect how screen recordings and AI processing work
Customize behavior: Modify capture intervals, deep-link actions, or AI prompts
Contribute: Fix bugs or add features with pull requests
Maximum privacy: Verify no data leaves your machine when using local AI
Debug issues: Run instrumented builds with enhanced logging

Prerequisites

System Requirements

macOS 13.0+ (Ventura or later)
Xcode 15+ (Download from Mac App Store)
Command Line Tools (installed automatically with Xcode or via xcode-select --install)

Optional: Gemini API Key

If you plan to use Gemini for AI processing, obtain a free API key:

Visit Google AI Studio
Sign in with your Google account
Click Get API Key → Create API key
Copy the key (starts with AIza...)

For local AI (Ollama/LM Studio) or ChatGPT/Claude CLI, no API key is needed.

Building Dayflow

Clone the repository

Open Terminal and clone the Dayflow repository:

git clone https://github.com/JerryZLiu/Dayflow.git
cd Dayflow

This downloads the complete source code to ~/Dayflow.

Open the Xcode project

open Dayflow.xcodeproj

Xcode will launch and load the project. Wait for indexing to complete (watch the progress bar in Xcode’s toolbar).

Configure code signing

In Xcode, select the Dayflow target in the project navigator.Go to Signing & Capabilities tab.For local development:

Set Team to your Apple ID or “None” (for unsigned local builds)
Xcode will auto-generate a provisioning profile

For distribution:

Use a paid Apple Developer account
Enable Hardened Runtime and Notarization for public release

Unsigned builds work fine locally but will trigger Gatekeeper warnings if shared with others.

Add GEMINI_API_KEY environment variable (optional)

If using Gemini, add your API key to the run scheme:

In Xcode, click the scheme selector (“Dayflow” near the top toolbar) → Edit Scheme…
Select Run in the left sidebar
Go to the Arguments tab
Under Environment Variables, click + to add:
- Name: GEMINI_API_KEY
- Value: AIzaSy... (your actual API key)

From README.md:177:

In your Run scheme, add your GEMINI_API_KEY under Arguments > Environment Variables (if using Gemini).

Never commit your API key to version control. The .gitignore excludes scheme files by default.

Build and run

Press Cmd+R or click the Run button (▶) in Xcode.Xcode will:

Compile Swift source files
Link frameworks (SwiftUI, ScreenCaptureKit, etc.)
Bundle resources (fonts, images)
Launch Dayflow in debug mode

First launch will prompt for Screen Recording permission.

Granting Permissions

When you run Dayflow for the first time, macOS will prompt for screen recording access.

Grant Screen Recording permission

When prompted, click Open System Settings.In Privacy & Security → Screen & System Audio Recording, enable the Dayflow checkbox.

Restart Dayflow

Quit Dayflow completely and re-run from Xcode (Cmd+R).From ScreenRecordingPermissionView.swift:183-189, permissions require a full app restart:

if CGPreflightScreenCaptureAccess() {
    permissionState = .granted
    Task { @MainActor in AppDelegate.allowTermination = false }
}

Build Configuration

Debug vs. Release

Debug (default for Xcode Run):

Enhanced logging (SQL query profiling, LLM call traces)
Slower performance due to optimizations disabled
Easier to debug with breakpoints and inspectors

Release (for Archive/Distribution):

Optimized for performance
Minimal logging
Smaller binary size

To switch:

Edit Scheme… → Run → Build Configuration
Select Debug or Release

Debug-Only Features

From StorageManager.swift:493-501, debug builds enable SQL profiling:

#if DEBUG
try? db.write { db in
    db.trace { event in
        if case .profile(let statement, let duration) = event, duration > 0.1 {
            print("📊 SLOW SQL (\(Int(duration * 1000))ms): \(statement)")
        }
    }
}
#endif

This logs all database queries taking >100ms to Console.app.

Project Structure

From README.md:304-311:

Dayflow/
├─ Dayflow/                 # SwiftUI app sources
│  ├─ App/                  # App lifecycle, deep-link routing
│  ├─ Core/                 # Recording, storage, AI services
│  ├─ Views/                # UI components, timeline, settings
│  └─ Utilities/            # Helpers, formatters, migrations
├─ docs/                    # Documentation assets, screenshots
├─ scripts/                 # Release automation (DMG, notarization)

Key files:

Dayflow/App/AppDeepLinkRouter.swift - URL scheme handling
Dayflow/Core/Recording/StorageManager.swift - Database and file management
Dayflow/Core/AI/GeminiService.swift - Gemini API integration
Dayflow/Views/Timeline/TimelineView.swift - Main timeline UI

Common Build Issues

”No signing certificate found”

Solution: In Signing & Capabilities, set Team to your Apple ID or “Sign to Run Locally” (Xcode 14+).

”ScreenCaptureKit not available”

Solution: Ensure deployment target is macOS 13.0+. Check Dayflow target → General → Minimum Deployments.

”Cannot find ‘GRDB’ in scope”

Solution: Xcode may need to resolve Swift Package Manager dependencies:

xcodebuild -resolvePackageDependencies

Or in Xcode: File → Packages → Resolve Package Versions.

Build succeeds but app crashes on launch

Solution: Check Console.app for crash logs. Common causes:

Missing Info.plist keys (screen recording usage description)
Corrupted database (delete ~/Library/Application Support/Dayflow/chunks.sqlite and rebuild)

Modifying the Source

Example: Change Recording Interval

By default, Dayflow captures in 60-second chunks. To change:

Open Dayflow/Core/Recording/ScreenRecorder.swift
Find the chunk duration constant (search for 60)

Modify the value:

private let chunkDuration: TimeInterval = 120 // 2-minute chunks

Rebuild (Cmd+B) and run

Example: Add Custom Deep-Link Action

To add a new URL action (e.g., dayflow://open-settings):

Open AppDeepLinkRouter.swift:10-24

Add new case to Action enum:

enum Action: String {
    case startRecording = "start-recording"
    case stopRecording = "stop-recording"
    case openSettings = "open-settings"  // New action
}

Update init?(identifier:) to handle the new action
Implement in perform(_ action:):
```
case .openSettings:
    openSettings()
```
Add the handler method and rebuild

Example: Customize AI Prompts

AI prompts are defined in service files like GeminiService.swift. To modify:

Search for prompt strings (look for systemInstruction or prompt constants)
Edit the prompt text
Rebuild and test with a small batch

Changing prompts may degrade timeline quality. Test thoroughly before relying on modified prompts.

Running Tests

Dayflow includes unit tests for core functionality:

# Run all tests from command line
xcodebuild test -scheme Dayflow -destination 'platform=macOS'

# Or in Xcode: Cmd+U

Tests cover:

Date/time calculations (4 AM boundary logic)
Database migrations
URL scheme routing
Storage management

Creating a Distribution Build

To create a .dmg for sharing:

Archive the app

In Xcode: Product → ArchiveWait for the build to complete (may take several minutes).

Export for distribution

When Organizer opens, select the archive → Distribute AppChoose Direct Distribution (for personal use) or Developer ID (for public release).

Notarize (optional but recommended)

For public distribution, enable notarization to avoid Gatekeeper warnings.Requires a paid Apple Developer account ($99/year).Xcode will upload to Apple’s notary service and staple the ticket automatically.

Create DMG (optional)

Dayflow includes release scripts in scripts/ for automated DMG creation.See scripts/release.sh for one-button release automation.

Staying Updated

To pull the latest changes from the repository:

cd ~/Dayflow
git fetch origin
git pull origin main

Then rebuild in Xcode.

Handling Merge Conflicts

If you’ve modified files locally:

# Stash your changes
git stash

# Pull updates
git pull origin main

# Re-apply your changes
git stash pop

Resolve any conflicts in Xcode, then rebuild.

Contributing

From README.md:332-334:

PRs welcome! If you plan a larger change, please open an issue first to discuss scope and approach.

Workflow:

Fork the repository on GitHub
Create a feature branch: git checkout -b feature/my-improvement
Make changes and commit: git commit -m "Add feature X"
Push to your fork: git push origin feature/my-improvement
Open a Pull Request on GitHub

Getting Help

If you encounter build issues:

Search GitHub Issues for similar problems
Check Xcode’s Report Navigator (Cmd+9) for detailed error logs
Try cleaning the build folder: Product → Clean Build Folder (Cmd+Shift+K)
If stuck, open a new issue with:
- Xcode version
- macOS version
- Complete error output
- Steps to reproduce

Debugging & Developer Tools - Inspect app behavior in debug builds
URL Scheme Automation - Test deep-link modifications

Get Started

Core Features

Configuration

Privacy & Security

Advanced

Building from Source

Why Build from Source?

Prerequisites

System Requirements

Optional: Gemini API Key

Building Dayflow

Granting Permissions

Build Configuration

Debug vs. Release

Debug-Only Features

Project Structure

Common Build Issues

”No signing certificate found”

”ScreenCaptureKit not available”

”Cannot find ‘GRDB’ in scope”

Build succeeds but app crashes on launch

Modifying the Source

Example: Change Recording Interval

Example: Add Custom Deep-Link Action

Example: Customize AI Prompts

Running Tests

Creating a Distribution Build

Staying Updated

Handling Merge Conflicts

Contributing

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Privacy & Security

Advanced

Documentation Index

​Why Build from Source?

​Prerequisites

​System Requirements

​Optional: Gemini API Key

​Building Dayflow

​Granting Permissions

​Build Configuration

​Debug vs. Release

​Debug-Only Features

​Project Structure

​Common Build Issues

​”No signing certificate found”

​”ScreenCaptureKit not available”

​”Cannot find ‘GRDB’ in scope”

​Build succeeds but app crashes on launch

​Modifying the Source

​Example: Change Recording Interval

​Example: Add Custom Deep-Link Action

​Example: Customize AI Prompts

​Running Tests

​Creating a Distribution Build

​Staying Updated

​Handling Merge Conflicts

​Contributing

​Getting Help

​Related Documentation

Build docs developers (and LLMs) love

Why Build from Source?

Prerequisites

System Requirements

Optional: Gemini API Key

Building Dayflow

Granting Permissions

Build Configuration

Debug vs. Release

Debug-Only Features

Project Structure

Common Build Issues

”No signing certificate found”

”ScreenCaptureKit not available”

”Cannot find ‘GRDB’ in scope”

Build succeeds but app crashes on launch

Modifying the Source

Example: Change Recording Interval

Example: Add Custom Deep-Link Action

Example: Customize AI Prompts

Running Tests

Creating a Distribution Build

Staying Updated

Handling Merge Conflicts

Contributing

Getting Help

Related Documentation