OmniFocus Task & Project Manager

Overview

Manage OmniFocus tasks and projects programmatically with intelligent automation that works across all OmniFocus versions. The skill automatically detects and uses the best available method:

Omni Automation (OmniFocus 3+) - Modern JavaScript API
AppleScript (All versions) - Compatible fallback
SQLite Read-Only (Last resort) - For analytics when automation unavailable

When to Use This Skill

Use this skill when users request to:

Create tasks: "Add task 'Review PR' to project 'Development'"
Read tasks: "Show me tasks in the 'Work' project"
Update tasks: "Mark task 'Call client' as complete"
List projects: "What projects do I have in OmniFocus?"
Query tasks: "Show me all tasks tagged with '@urgent'"
Manage workflows: "Create project tasks for new feature development"

Core Capabilities

1. Create Tasks

Add new tasks to OmniFocus with full metadata support.

Usage:

scripts/omnifocus_manager.rb --create \
  --name "Review pull request #42" \
  --project "Development" \
  --notes "Check for security issues and code quality"

Claude Integration:

# When user says: "Add task to OmniFocus to review the API documentation"
ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --create \
  --name "Review API documentation" \
  --project "Documentation"

Supported Parameters:

--name (required): Task title
--project (optional): Project name (creates if doesn't exist)
--notes (optional): Task notes/description
--tag (optional): Tag to assign (repeatable for multiple tags)
--due (optional): Due date (ISO 8601 format)

2. Read Tasks

Query tasks with powerful filtering options.

Usage:

# All incomplete tasks
scripts/omnifocus_manager.rb --read

# Tasks in specific project
scripts/omnifocus_manager.rb --read --project "Development"

# Tasks with specific tag
scripts/omnifocus_manager.rb --read --tag "@urgent"

# Include completed tasks
scripts/omnifocus_manager.rb --read --completed

# Limit results
scripts/omnifocus_manager.rb --read --limit 50

Claude Integration:

# When user says: "What tasks do I have in my Work project?"
ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --read \
  --project "Work"

Output Format (JSON):

[
  {
    "id": "abc123xyz",
    "name": "Review pull request #42",
    "completed": false,
    "note": "Check for security issues",
    "project": "Development",
    "dueDate": "2025-11-25T17:00:00Z",
    "tags": ["@code-review", "@high-priority"]
  }
]

3. Update Tasks

Modify existing tasks programmatically.

Usage:

# Mark task complete
scripts/omnifocus_manager.rb --update TASK_ID --completed

# Update task name
scripts/omnifocus_manager.rb --update TASK_ID --name "New task title"

# Update notes
scripts/omnifocus_manager.rb --update TASK_ID --notes "Updated description"

Claude Integration:

# When user says: "Mark the task 'Call client' as done"
# First, find the task ID
TASK_ID=$(ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --read | jq -r '.[] | select(.name == "Call client") | .id')

# Then mark it complete
ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --update "$TASK_ID" \
  --completed

4. List Projects

View all OmniFocus projects.

Usage:

scripts/omnifocus_manager.rb --list-projects

Output Format (JSON):

[
  {
    "id": "proj123",
    "name": "Development",
    "status": "active",
    "note": "Software development tasks",
    "taskCount": 15
  },
  {
    "id": "proj456",
    "name": "Marketing",
    "status": "active",
    "note": "",
    "taskCount": 8
  }
]

Automation Method Detection

The skill automatically detects and uses the best available automation method:

Priority Order

Omni Automation (Preferred)
- Modern JavaScript API
- OmniFocus 3+ required
- Cross-platform (Mac, iOS, iPad)
- Full read/write capabilities
- Fastest performance
AppleScript (Compatible)
- Works with all OmniFocus versions
- macOS only
- Full read/write capabilities
- Requires OmniFocus Pro for automation
SQLite Read-Only (Fallback)
- Last resort when automation unavailable
- Read operations only
- No permissions required
- Useful for analytics and reporting

Detection is automatic - no configuration needed. The manager checks availability in order and uses the first working method.

Permission Requirements

Omni Automation

Minimal: Enable Automation in OmniFocus Preferences → Automation
No system-level permissions required

AppleScript

System Permission: System Preferences → Security & Privacy → Privacy → Automation
User prompted on first use
Must grant permission for controlling application to control OmniFocus

SQLite Read-Only

File System Access: Read access to ~/Library/Caches/
No automation permissions needed
Read-only operations only

Setup Guidance

When encountering permission errors, guide users to:

Open System Preferences (or System Settings on macOS 13+)
Navigate to Security & Privacy → Privacy → Automation
Find the controlling application (e.g., Terminal, Ruby, Claude Code)
Enable checkbox for OmniFocus
Restart the application if needed

Common Workflows

Workflow 1: Create Project with Tasks

# Create project by adding first task
ruby scripts/omnifocus_manager.rb --create \
  --name "Set up database schema" \
  --project "New Feature Development"

# Add more tasks to the project
ruby scripts/omnifocus_manager.rb --create \
  --name "Implement API endpoints" \
  --project "New Feature Development"

ruby scripts/omnifocus_manager.rb --create \
  --name "Write unit tests" \
  --project "New Feature Development"

Workflow 2: Daily Task Review

# Get all incomplete tasks
ruby scripts/omnifocus_manager.rb --read > /tmp/tasks.json

# Process with jq for specific queries
cat /tmp/tasks.json | jq '.[] | select(.dueDate != null) | {name, dueDate}'

Workflow 3: Bulk Task Completion

# Find all tasks matching criteria
ruby scripts/omnifocus_manager.rb --read --project "Sprint 23" > /tmp/sprint_tasks.json

# Mark each as complete
cat /tmp/sprint_tasks.json | jq -r '.[].id' | while read task_id; do
  ruby scripts/omnifocus_manager.rb --update "$task_id" --completed
done

Workflow 4: Task Analytics

# Count tasks by project (using read-only SQLite)
ruby scripts/omnifocus_manager.rb --read | \
  jq 'group_by(.project) | map({project: .[0].project, count: length})'

Claude Usage Patterns

Pattern 1: Natural Language Task Creation

User Request: "Add a task to call the client about Q4 planning to my Work project"

Claude Response:

ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --create \
  --name "Call client about Q4 planning" \
  --project "Work"

Pattern 2: Task Query with Formatting

User Request: "Show me my urgent tasks"

Claude Response:

# Query urgent tasks
ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --read \
  --tag "@urgent" | \
  jq -r '.[] | "- \(.name) [\(.project // "Inbox")]"'

Pattern 3: Task Status Updates

User Request: "I finished the code review task"

Claude Response:

# Find task ID
TASK_ID=$(ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --read | \
  jq -r '.[] | select(.name | contains("code review")) | .id' | head -1)

# Mark complete
if [ -n "$TASK_ID" ]; then
  ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
    --update "$TASK_ID" \
    --completed
  echo "✅ Task marked as complete"
else
  echo "❌ Task not found"
fi

Pattern 4: Project Overview

User Request: "What's in my Development project?"

Claude Response:

ruby ~/.claude/skills/omnifocus/scripts/omnifocus_manager.rb \
  --read \
  --project "Development" | \
  jq -r '
    "Development Project Tasks:\n" +
    "Total: \(length)\n" +
    "Incomplete: \([.[] | select(.completed == false)] | length)\n\n" +
    "Tasks:\n" +
    (.[] | "- [\(if .completed then "x" else " " end)] \(.name)")
  '

Troubleshooting

Issue: "Omni Automation Error: Application isn't running"

Solution: Start OmniFocus application

open -a OmniFocus
sleep 2  # Wait for app to launch
# Retry operation

Issue: "AppleScript Error: Not authorized"

Solution: Grant automation permissions

System Preferences → Security & Privacy → Privacy → Automation
Enable checkbox for controlling app → OmniFocus
Restart controlling application

Issue: "Task not found" when updating

Solution: Verify task ID exists

# List all task IDs
ruby scripts/omnifocus_manager.rb --read | jq -r '.[].id'

# Or search for task by name
ruby scripts/omnifocus_manager.rb --read | jq '.[] | select(.name | contains("search term"))'

Issue: "OmniFocus database not found"

Solution: Verify OmniFocus is installed and has been run at least once

ls -la ~/Library/Caches/com.omnigroup.OmniFocus*

Issue: "Write operations not available"

Explanation: Only read-only SQLite access is available Solution: Enable Omni Automation or grant AppleScript permissions for write operations

Advanced Usage

Programmatic Integration

Use the Ruby API directly for custom integrations:

require_relative 'scripts/omnifocus_manager'

manager = OmniFocusManager.new
puts "Using automation: #{manager.automation_type}"

# Create task
result = manager.create_task(
  name: "Process expense report",
  project: "Finance",
  notes: "Q4 2025 expenses",
  tags: ["@admin", "@urgent"]
)

# Read tasks
tasks = manager.read_tasks(project: "Finance", completed: false)
tasks.each do |task|
  puts "#{task['name']} - #{task['completed'] ? '✓' : '○'}"
end

JSON Output Processing

All commands output JSON for easy processing with jq:

# Tasks due this week
ruby scripts/omnifocus_manager.rb --read | \
  jq '.[] | select(.dueDate != null and (.dueDate | fromdateiso8601) < (now + 604800))'

# Group by project
ruby scripts/omnifocus_manager.rb --read | \
  jq 'group_by(.project) | map({project: .[0].project, tasks: map(.name)})'

# Export to CSV
ruby scripts/omnifocus_manager.rb --read | \
  jq -r '["Name","Project","Completed","Due Date"], (.[] | [.name, .project, .completed, .dueDate]) | @csv'

Performance Considerations

Omni Automation: Fastest, direct API access (~100-200ms per operation)
AppleScript: Moderate speed (~200-500ms per operation)
SQLite: Very fast for reads (~10-50ms), but read-only

For bulk operations (>100 tasks), consider:

Using SQLite read-only for queries
Batching write operations
Caching project IDs to avoid repeated lookups

Resources

See references/api_reference.md for detailed API documentation including:

Complete Omni Automation JavaScript API reference
AppleScript object model and properties
SQLite database schema details
Advanced query examples

Version Compatibility

OmniFocus 3+: Full Omni Automation support
OmniFocus 2: AppleScript only
OmniFocus 1: AppleScript only
All versions: SQLite read-only fallback

Security & Privacy

No data transmission: All operations are local
Read-only by default: SQLite fallback is read-only to prevent corruption
Permission-gated: Requires explicit user authorization for automation
Temporary database copies: SQLite operations use copies, never modify live database