Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JerryZLiu/Dayflow/llms.txt

Use this file to discover all available pages before exploring further.

Accessing Debug Tools

Dayflow provides built-in debugging features accessible from the menu bar icon and filesystem.

Saved Recordings

Opening the Recordings Folder

Click the Dayflow icon in the menu barOpen Recordings to view all captured content. From StatusMenuView.swift:70-75:
private func openRecordingsFolder() {
    performAfterMenuDismiss {
        let directory = StorageManager.shared.recordingsRoot
        NSWorkspace.shared.open(directory)
    }
}

Recording Storage Location

All recordings are stored in:
~/Library/Application Support/Dayflow/recordings/
This directory contains:
  • Video chunks (.mp4 files) - Screen recordings captured in 60-second segments
  • Screenshots (.jpg files) - Periodic screen captures (newer capture method)
  • Timelapse videos - Generated summaries for timeline cards

File Naming Convention

Files are named with timestamp format:
yyyyMMdd_HHmmssSSS.mp4
yyyyMMdd_HHmmssSSS.jpg
Example: 20260303_143052847.mp4 = captured on March 3, 2026 at 2:30:52.847 PM

Database Location

Dayflow uses SQLite for metadata storage:
~/Library/Application Support/Dayflow/chunks.sqlite
Database schema includes:
  • chunks - Video recording segments
  • screenshots - Screen captures with timestamps
  • analysis_batches - Groupings sent to AI for processing
  • timeline_cards - Generated activity summaries
  • observations - AI transcription outputs
  • llm_calls - Detailed logs of all LLM API requests
You can inspect the database with any SQLite browser or CLI:
sqlite3 ~/Library/Application\ Support/Dayflow/chunks.sqlite

Viewing Batch Contents

What Are Batches?

Batches group recording chunks for AI processing. Each batch represents a time window analyzed together to generate timeline cards. From StorageManager.swift:656-674, batches track:
  • Start/end timestamps
  • Processing status (pending, processing, completed, failed)
  • Associated chunks or screenshots
  • LLM metadata (API calls, latency, errors)

Debug Log Export

Dayflow can generate detailed debug logs with batch, LLM, and timeline data. The DebugLogFormatter.swift utility formats: Timeline cards:
--- Timeline cards (latest 50) ---
1. [2026-03-03] 2:30 PM-3:45 PM | Writing documentation | Work / Development | created 2026-03-03 14:30:00
   Summary: Drafted advanced debugging documentation for Dayflow
   Details: Created comprehensive guide covering recordings access, batch inspection, and troubleshooting
LLM calls:
--- LLM calls (latest 50) ---  
1. 2026-03-03 14:35:12 | gemini | gemini-2.0-flash-exp | generate_cards | success | 1847ms | HTTP 200
   batch 42, group abc123, attempt 1
   POST https://generativelanguage.googleapis.com/v1beta/...
Analysis batches:
--- Analysis batches (latest 50) ---
1. id=42 | status=completed | created 2026-03-03 14:30:00
   window: 2026-03-03 14:00:00 → 2026-03-03 14:30:00
   reason: scheduled_interval
Access this via internal debug views (implementation may vary by version).

Logs and Console Output

Application Logs

Dayflow logs to the unified logging system. View logs in real-time:
log stream --predicate 'processImagePath contains "Dayflow"' --level debug

Filtering by Category

Dayflow uses category prefixes for different subsystems:
# Deep-link events
log stream --predicate 'processImagePath contains "Dayflow"' | grep DeepLink

# Database operations  
log stream --predicate 'processImagePath contains "Dayflow"' | grep "DB write"

# Slow queries (>100ms)
log stream --predicate 'processImagePath contains "Dayflow"' | grep "SLOW"

Crash Reports

Crash logs are stored in:
~/Library/Logs/DiagnosticReports/Dayflow_*.crash
If Dayflow crashes, check this directory for stack traces.

Troubleshooting Common Issues

Blank Screen Capture

Symptom: Timeline shows blank or black frames Causes:
  1. Screen Recording permission not granted
  2. Permission granted but app not restarted
  3. Recording during screen lock/screensaver
Solutions:
1

Verify Screen Recording permission

Go to System Settings → Privacy & Security → Screen & System Audio RecordingEnsure Dayflow is enabled.
2

Restart Dayflow after granting permission

Quit Dayflow completely from the menu bar → Quit CompletelyRelaunch from Applications folder.From ScreenRecordingPermissionView.swift:183-189, permissions require a full restart:
if CGPreflightScreenCaptureAccess() {
    permissionState = .granted
    Task { @MainActor in AppDelegate.allowTermination = false }
}
3

Check for screen lock conflicts

Screen capture may fail during lock. Review timeline for gaps during known lock periods.
4

Inspect recordings folder

Open recordings folder from menu bar → verify files have non-zero size:
ls -lh ~/Library/Application\ Support/Dayflow/recordings/
Files under 1KB indicate capture failures.

API Errors (Gemini/ChatGPT/Claude)

Symptom: Timeline stops generating, batches stuck in “processing” Causes:
  1. Invalid or expired API key
  2. Network connectivity issues
  3. API quota exceeded
  4. Rate limiting
Solutions:
1

Verify API key configuration

Go to Dayflow Settings → AI ProviderRe-enter your API key if using Gemini.For ChatGPT/Claude CLI: ensure you’re logged in:
# ChatGPT Codex CLI
codex auth status

# Claude Code
claude auth status
2

Check network connectivity

Verify internet connection and firewall settings.Test API access directly:
curl -H "x-goog-api-key: YOUR_KEY" \
  https://generativelanguage.googleapis.com/v1beta/models
3

Review LLM call logs

Check Console.app for HTTP errors:
log stream --predicate 'processImagePath contains "Dayflow"' | grep "HTTP"
Look for 401 (auth), 429 (rate limit), or 500 (server error) responses.
4

Inspect database for failed batches

sqlite3 ~/Library/Application\ Support/Dayflow/chunks.sqlite \
  "SELECT id, status, reason FROM analysis_batches WHERE status='failed' ORDER BY id DESC LIMIT 10;"
The reason column may contain error details.

Permission Issues After macOS Update

Symptom: Dayflow stops capturing after a macOS update Solution:
1

Re-grant Screen Recording permission

macOS updates sometimes reset TCC (Transparency, Consent, and Control) permissions.Go to System Settings → Privacy & Security → Screen & System Audio RecordingToggle Dayflow off then on.
2

Restart Dayflow completely

Menu bar → Quit Completely (don’t just hide the window)Launch from Applications folder.
3

If issue persists, reset TCC database (advanced)

tccutil reset ScreenCapture com.teleportlabs.Dayflow
Then re-grant permission in System Settings and restart.

High CPU or Memory Usage

Symptom: Dayflow using excessive resources Diagnostics:
# Check current resource usage
top -pid $(pgrep Dayflow)

# Sample for 10 seconds to identify hot code paths
sample Dayflow 10 -f ~/Desktop/dayflow_sample.txt
Common causes:
  1. Large batch processing: CPU spikes during AI analysis are normal
  2. Database contention: Check for slow queries in logs
  3. Storage cleanup running: Hourly purge may briefly increase I/O
Solutions:
  • Reduce recording quality in settings (if available)
  • Increase storage limit to reduce purge frequency
  • For local AI: ensure model is fully loaded in VRAM (check Ollama/LM Studio logs)

Missing Timeline Cards

Symptom: Recordings exist but timeline is empty Diagnostics:
# Check for completed but unprocessed chunks
sqlite3 ~/Library/Application\ Support/Dayflow/chunks.sqlite \
  "SELECT COUNT(*) FROM chunks WHERE status='completed' AND id NOT IN (SELECT chunk_id FROM batch_chunks);"

# Check for pending batches
sqlite3 ~/Library/Application\ Support/Dayflow/chunks.sqlite \
  "SELECT COUNT(*) FROM analysis_batches WHERE status='pending';"
If unprocessed chunks exist but no pending batches, the batch scheduler may have stalled. Solution: Restart Dayflow to resume batch processing.

Debug Build Features

When building from source with DEBUG configuration, additional logging is enabled: From StorageManager.swift:493-501:
#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 SQL queries taking >100ms to Console.app.

Advanced: Inspecting SQLite Database

Useful Queries

Recent timeline cards:
SELECT day, start, end, title, category 
FROM timeline_cards 
WHERE is_deleted = 0 
ORDER BY start_ts DESC 
LIMIT 20;
LLM call statistics:
SELECT provider, operation, status, COUNT(*) as count, AVG(latency_ms) as avg_ms
FROM llm_calls
GROUP BY provider, operation, status
ORDER BY count DESC;
Storage usage by day:
SELECT day, COUNT(*) as card_count, SUM(end_ts - start_ts) as total_seconds
FROM timeline_cards
WHERE is_deleted = 0
GROUP BY day
ORDER BY day DESC
LIMIT 30;

Backup Database

Before manual edits, backup the database:
cp ~/Library/Application\ Support/Dayflow/chunks.sqlite \
   ~/Desktop/dayflow_backup_$(date +%Y%m%d).sqlite
Dayflow also creates automatic backups in:
~/Library/Application Support/Dayflow/backups/

Getting Help

If troubleshooting doesn’t resolve your issue:
  1. Check GitHub Issues for similar problems
  2. Collect debug info:
    • Console.app logs filtered for Dayflow
    • Recent timeline cards and batch status from database
    • System info: macOS version, Dayflow version (menu bar → About)
  3. Open a new issue with details

Build docs developers (and LLMs) love