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.

User asks about…Command to runsummary / overview / stats.claude/skills/omnifocus4/scripts/of summaryinbox.claude/skills/omnifocus4/scripts/of inboxtoday / overdue / due.claude/skills/omnifocus4/scripts/of todayflagged tasks.claude/skills/omnifocus4/scripts/of flaggedwhat to do / available tasks.claude/skills/omnifocus4/scripts/of available 10projects.claude/skills/omnifocus4/scripts/of projectssearch for something.claude/skills/omnifocus4/scripts/of search "query"

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#

bash

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

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

Commands#

Read#

CommandArgsDescriptioninboxList inbox tasksfoldersList all foldersprojects``[folder] [--all]List active projects (default); --all includes on-hold, dropped, completedtasks``<project>List tasks in a projecttags``[--all]List tags with available tasks (default); --all includes empty tagstodayTasks due today or overdueflaggedFlagged incomplete taskssearch``<query>Search tasks by name or noteinfo``<taskId>Full task details by IDsummaryDatabase counts (projects, tasks, flagged, due, available, inbox)project-tree``<name> [limit]Recursive subtask tree with depthproject-search``<term> [limit]Find projects by partial namefolder``<name> [limit]Detail a folder: child folders + projects (default limit 50 — use a higher limit for large folders)root``[limit]Top-level folders and unfiled projectstag-summary``<name> [limit]Tasks for a tag, grouped by folder/projecttag-family``<name> [limit]Tasks across a tag and all its childrenavailable``[limit]All available (actionable) tasksreview``[limit] [--all]Active projects with task counts (default); --all includes all statuses

Create#

CommandArgsDescriptionadd``<name> [project]Add task to inbox or projectnewproject``<name> [folder]Create projectnewfolder``<name>Create top-level foldernewtag``<name>Create or get tag

Modify#

CommandArgsDescriptioncomplete``<taskId>Mark completeuncomplete``<taskId>Mark incompletedelete``<taskId>Permanently deleterename``<taskId> <name>Rename tasknote``<taskId> <text>Append to notesetnote``<taskId> <text>Replace notedefer``<taskId> <date>Set defer date (YYYY-MM-DD)due``<taskId> <date>Set due date (YYYY-MM-DD)flag``<taskId> [true|false]Set flagged (default true)tag``<taskId> <tag>Add tag (creates if needed)untag``<taskId> <tag>Remove tagmove``<taskId> <project>Move to project

Repeat#

bash

# 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:

json

{
  "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#

bash

# 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