OmniFocus

IMPORTANT: OmniFocus data is live. When asked anything about tasks, projects, inbox, flagged items, due dates, or reviews — RUN A COMMAND. Do not answer from memory, do not say you cannot access OmniFocus, do not ask clarifying questions. Just run the appropriate command below and return the result.

How to invoke

Call of directly with the Bash tool. Do not wrap in AppleScript do shell script "..." and do not route through mcp__Control_your_Mac__osascript — the script handles the AppleScript → Omni Automation bridge internally.

• Local Claude Code (macOS): the sandbox blocks inter-process AppleScript. Pass dangerouslyDisableSandbox: true on every Bash call. An error like -600 "Application isn't running" is a sandbox symptom, not a real OmniFocus state.
• Cowork / remote / other environments: just call Bash. If the host has no access to a running OmniFocus, commands will fail with a real connection error — report that to the user rather than retrying with AppleScript wrappers.

Control OmniFocus via Omni Automation JS, called from a Python wrapper.

Requirements

• macOS with OmniFocus 3 or 4 installed
• OmniFocus must be running (or will auto-launch)
• Python 3 (system Python is fine)

Quick Reference

.claude/skills/omnifocus4/scripts/of <command> [args...]

All commands return JSON to stdout. Errors print {"error": "..."} and exit 1.

Commands

Read

Create

Modify

Repeat

# repeat <taskId> <method> <interval> <unit>
.claude/skills/omnifocus4/scripts/of repeat abc123 fixed 1 weeks
.claude/skills/omnifocus4/scripts/of repeat abc123 due-after-completion 2 days
.claude/skills/omnifocus4/scripts/of repeat abc123 defer-after-completion 1 months
.claude/skills/omnifocus4/scripts/of unrepeat abc123

Methods: fixed, due-after-completion, defer-after-completion Units: days, weeks, months, years

Output Format

All commands return JSON. Task records include:

{
  "id": "abc123",
  "name": "Task name",
  "note": "Notes here",
  "flagged": false,
  "completed": false,
  "available": true,
  "deferDate": "2026-04-01",
  "dueDate": "2026-04-10",
  "effectiveDueDate": "2026-04-10",
  "completionDate": null,
  "estimatedMinutes": 30,
  "project": "Project Name",
  "folder": "Folder Name",
  "tags": ["tag1", "tag2"],
  "repeat": {"method": "fixed", "recurrence": "FREQ=WEEKLY;INTERVAL=1"}
}

Write commands return {"success": true, "task": {...}}.

Examples

# Add task to inbox
.claude/skills/omnifocus4/scripts/of add "Buy groceries"

# Add task to specific project
.claude/skills/omnifocus4/scripts/of add "Review docs" "Work Projects"

# Get today's tasks
.claude/skills/omnifocus4/scripts/of today

# Search name and notes
.claude/skills/omnifocus4/scripts/of search "quarterly report"

# Set due date and flag
.claude/skills/omnifocus4/scripts/of due abc123 2026-04-10
.claude/skills/omnifocus4/scripts/of flag abc123 true

# Add tags
.claude/skills/omnifocus4/scripts/of tag abc123 "urgent"

# Create recurring task
.claude/skills/omnifocus4/scripts/of add "Weekly review" "Habits"
.claude/skills/omnifocus4/scripts/of repeat xyz789 fixed 1 weeks

# Hierarchical views
.claude/skills/omnifocus4/scripts/of summary
.claude/skills/omnifocus4/scripts/of root
.claude/skills/omnifocus4/scripts/of folder "Personal"
.claude/skills/omnifocus4/scripts/of project-tree "Work" 50
.claude/skills/omnifocus4/scripts/of tag-family "review"

Performance

OmniJS loads all task objects on first access (~5-7 s for large databases). Commands are grouped by expected latency:

Fast (<1 s): inbox, folders, root, folder, projects, project-search, project-tree, tags, tag-summary, tag-family

Medium (4-6 s): summary, flagged, today, search, available, review

Prefer fast structural commands for navigation. Use medium commands only when task-level data is actually needed — and batch related queries when possible (e.g. ask for flagged once rather than flagged + available separately).

Technical Details

Uses Omni Automation JS evaluated inside OmniFocus via AppleScript evaluate javascript. This is more reliable than JXA for OmniFocus-specific APIs — no cross-process type-conversion bugs.

Key implementation patterns:

• filter() not byName() — byName() returns an ObjectSpecifier proxy whose child collections fail to enumerate
• asArray() helper — Array.isArray() returns false for OmniJS collection types
• safe() wrapper — prevents crashes on null/undefined properties
• id.primaryKey — stable canonical ID in Omni Automation
• effectiveDueDate — respects project-cascaded due dates
• Dates output as ISO 8601 YYYY-MM-DD via Date.toISOString()
• isAvailableApprox — fast approximation: not completed + not deferred to future
• listTaskRecord / listProjectRecord — slim records for bulk list commands

First run: OmniFocus may prompt to allow automation access. Enable in System Settings > Privacy & Security > Automation.

Notes

• Task IDs are OmniFocus internal primary keys (returned in all task responses)
• Dates use ISO 8601: YYYY-MM-DD
• Project and tag names are case-sensitive
• Tags are created automatically when using tag command
• isAvailableApprox respects defer dates but not sequential project ordering