Building & Debugging

Learn how to build, run, and debug Dayflow in your local development environment.

Building in Xcode

Select the Dayflow scheme

In Xcode’s toolbar, ensure the Dayflow scheme is selected with My Mac as the destination.

Build the project

Build the app using one of these methods:

Press Cmd + B
Select Product → Build from the menu
Click the Play button (▶) to build and run

Run the app

Press Cmd + R or click the Play button to build and launch Dayflow.

On first launch, macOS will prompt you to grant Screen & System Audio Recording permissions. Go to System Settings → Privacy & Security → Screen & System Audio Recording and enable Dayflow.

Configuring the Run Scheme

Dayflow requires environment variables for AI provider integration. Here’s how to configure them:

Open scheme editor

In Xcode, go to Product → Scheme → Edit Scheme… (or press Cmd + <).

Add environment variables

Select Run in the left sidebar
Click the Arguments tab
Expand the Environment Variables section
Click the + button to add variables

Configure AI provider

Add the following environment variables based on your AI provider:

Gemini (Google AI)

Variable	Value	Description
`GEMINI_API_KEY`	Your API key	Get from Google AI Studio

Local Models (Ollama/LM Studio)

No environment variables required. Ensure Ollama or LM Studio is running locally.

ChatGPT/Claude (CLI-based)

No environment variables required. Install and authenticate the CLI tools:

ChatGPT: Install Codex CLI and sign in
Claude: Install Claude Code and sign in

Environment variables set in the scheme editor only affect debug builds in Xcode. For release builds, see Build Automation.

Debugging Tips

Using Xcode Debugger

Set breakpoints - Click the line number gutter to add breakpoints
Inspect variables - Hover over variables or use the Variables View when paused
Debug console - Use po (print object) command to inspect objects
```
po someVariable
```
View hierarchy - Click the Debug View Hierarchy button during runtime to inspect UI

Dayflow includes built-in developer tools accessible from the menu bar:

View recordings - Click the Dayflow menu bar icon and select “Open Recordings…” to inspect captured video chunks
Debug UI - The app includes debug views for analyzing the capture and analysis pipeline
Database inspection - Local database is stored at ~/Library/Application Support/Dayflow/chunks.sqlite

Recording files are saved to ~/Library/Application Support/Dayflow/recordings/

Console Logging

View system logs for Dayflow:

# View live logs
log stream --predicate 'subsystem == "com.teleportlabs.Dayflow"' --level debug

# Or use Console.app and filter by "Dayflow"

Common Build Issues

Code signing errors

Problem: “Signing for ‘Dayflow’ requires a development team.”Solution:

Select the Dayflow target in Xcode
Go to Signing & Capabilities tab
Check Automatically manage signing
Select your Apple ID team from the dropdown

Missing permissions at runtime

Problem: App launches but screen capture is blank.Solution:

Open System Settings → Privacy & Security → Screen & System Audio Recording
Enable Dayflow
Restart the app

See Apple’s documentation for details.

Build fails with 'Swift compiler error'

Problem: Generic Swift compilation errors.Solution:

Clean build folder: Product → Clean Build Folder (Cmd + Shift + K)
Delete derived data: rm -rf ~/Library/Developer/Xcode/DerivedData/Dayflow-*
Restart Xcode and rebuild

Sparkle framework errors

Problem: Missing or unsigned Sparkle framework.Solution: Sparkle is included as a dependency. If you encounter issues:

Ensure you’re using the latest commit from the repository
Clean and rebuild the project
Check that Dayflow/Dayflow.xcodeproj includes the Sparkle framework

Build Automation

Dayflow includes powerful build automation scripts for creating release builds. These scripts handle building, code signing, notarization, and distribution.

Release Scripts Overview

The scripts/ directory contains automation for the entire release process:

`release_dmg.sh`

Builds, signs, notarizes, and packages a distribution-ready DMG. What it does:

Builds Dayflow in Release configuration with code signing disabled
Uploads dSYMs to Sentry for crash symbolication (if configured)
Determines your Developer ID signing identity
Creates a sanitized app copy without extended attributes
Re-signs all frameworks (Sparkle, Sentry) and the app bundle with runtime hardening
Creates a styled DMG with custom background using create-dmg
Submits the DMG to Apple for notarization
Staples the notarization ticket to the DMG

Key environment variables:

SIGN_ID - Developer ID Application identity (auto-detected if not set)
NOTARY_PROFILE - Saved notarytool keychain profile
NOTARY_APPLE_ID, NOTARY_TEAM_ID, NOTARY_APP_PASSWORD - Alternative notarization credentials
NO_NOTARIZE=1 - Skip notarization (for testing)

Usage:

./scripts/release_dmg.sh

`release.sh`

Complete one-button release workflow that orchestrates the entire release process. What it does:

Bumps version number (minor by default; use --major or --patch to override)
Updates MARKETING_VERSION and CURRENT_PROJECT_VERSION in Xcode project
Syncs Info.plist values
Calls release_dmg.sh to build, sign, and notarize
Signs the update with Sparkle’s sign_update tool (EdDSA signature)
Creates a draft GitHub Release and uploads the DMG
Publishes the release (undrafts)
Updates docs/appcast.xml with the new version for Sparkle auto-updates
Commits changes and pushes to GitHub

Usage:

# Bump minor version (e.g., 1.2.0 → 1.3.0)
./scripts/release.sh

# Bump major version (e.g., 1.2.0 → 2.0.0)
./scripts/release.sh --major

# Bump patch version (e.g., 1.2.0 → 1.2.1)
./scripts/release.sh --patch

# Dry run (shows what would happen)
./scripts/release.sh --dry-run

# Include custom release notes
./scripts/release.sh --notes release-notes.md

Requirements:

Xcode + Developer ID certificate in login keychain
sign_update (Sparkle CLI) in PATH
gh CLI authenticated (gh auth login)
Sparkle private key in Keychain (generated by generate_keys)
create-dmg installed (brew install create-dmg)

`update_appcast.sh`

Prepends a new release item to the Sparkle appcast XML feed. Usage:

./scripts/update_appcast.sh \
  --dmg Dayflow.dmg \
  --url https://github.com/user/repo/releases/download/v1.2.3/Dayflow.dmg \
  --short 1.2.3 \
  --build 123 \
  --signature <BASE64_EDDSA_SIG> \
  --msv 13.0 \
  --notes https://github.com/user/repo/releases/tag/v1.2.3 \
  --out docs/appcast.xml

The appcast feed is used by Sparkle to notify users of updates. It’s hosted at https://dayflow.so/appcast.xml via GitHub Pages.

Setting Up Release Automation

To use the release scripts, you’ll need to configure credentials:

Create release.env

Copy the example configuration:

cp scripts/release.env.example scripts/release.env

Configure credentials

Edit scripts/release.env and add your credentials:

# Code signing
SIGN_ID="Developer ID Application: Your Name (TEAMID)"

# Notarization (choose one method)
NOTARY_PROFILE="your-profile-name"  # Recommended: saved keychain profile
# OR
NOTARY_APPLE_ID="your@email.com"
NOTARY_TEAM_ID="TEAMID"
NOTARY_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"  # App-specific password

# Optional: Crash reporting (Sentry)
SENTRY_AUTH_TOKEN="your-token"
SENTRY_ORG="your-org"
SENTRY_PROJECT="dayflow"
SENTRY_DSN="https://xxx@sentry.io/xxx"

# Optional: Analytics (PostHog)
POSTHOG_API_KEY="phc_xxx"
POSTHOG_HOST="https://app.posthog.com"

Use xcrun notarytool store-credentials to save a keychain profile for easier notarization.

Install dependencies

Install required tools:

# Install create-dmg for styled DMG creation
brew install create-dmg

# Install Sparkle's sign_update tool
# Download from https://github.com/sparkle-project/Sparkle/releases
# Or build from source and add to PATH

# Authenticate GitHub CLI
gh auth login

# Optional: Install sentry-cli for crash reporting
brew install getsentry/tools/sentry-cli

scripts/release.env contains sensitive credentials and is gitignored. Never commit this file to version control.

Build Configuration Details

The release scripts use these Xcode build settings:

Scheme: Dayflow
Configuration: Release
Derived Data: build/ (local directory)
Code Signing: Disabled during build, applied manually afterward for proper Sparkle/Sentry framework signing
Hardened Runtime: Enabled with entitlements for Sparkle’s XPC services

Next Steps

Review Contributing Guidelines before submitting changes
Read the README for architecture details
Join discussions on GitHub Issues

Architecture

Contributing

Building & Debugging

Building in Xcode

Configuring the Run Scheme

Gemini (Google AI)

Local Models (Ollama/LM Studio)

ChatGPT/Claude (CLI-based)

Debugging Tips

Using Xcode Debugger

Debug Menu in Dayflow

Console Logging

Common Build Issues

Build Automation

Release Scripts Overview

`release_dmg.sh`

`release.sh`

`update_appcast.sh`

Setting Up Release Automation

Build Configuration Details

Next Steps

Build docs developers (and LLMs) love

Architecture

Contributing

Documentation Index

​Building in Xcode

​Configuring the Run Scheme

​Gemini (Google AI)

​Local Models (Ollama/LM Studio)

​ChatGPT/Claude (CLI-based)

​Debugging Tips

​Using Xcode Debugger

​Debug Menu in Dayflow

​Console Logging

​Common Build Issues

​Build Automation

​Release Scripts Overview

​release_dmg.sh

​release.sh

​update_appcast.sh

​Setting Up Release Automation

​Build Configuration Details

​Next Steps

Build docs developers (and LLMs) love

Building in Xcode

Configuring the Run Scheme

Gemini (Google AI)

Local Models (Ollama/LM Studio)

ChatGPT/Claude (CLI-based)

Debugging Tips

Using Xcode Debugger

Debug Menu in Dayflow

Console Logging

Common Build Issues

Build Automation

Release Scripts Overview

`release_dmg.sh`

`release.sh`

`update_appcast.sh`

Setting Up Release Automation

Build Configuration Details

Next Steps