omnifocus

OmniFocus Task Management

Automate OmniFocus task management via JavaScript for Automation (JXA) scripts.

Quick Start

All scripts are located in the scripts/ directory and use JXA. Run with:

osascript -l JavaScript scripts/<script-name>.js [args]

Key Scripts:

• add_task.js - Add task to inbox
• list_tasks.js - List tasks with filters
• search_tasks.js - Search tasks by keyword
• complete_task.js - Complete a task by name
• update_task.js - Update task properties
• get_stats.js - Get OmniFocus statistics

Core Operations

Adding Tasks

osascript -l JavaScript scripts/add_task.js "Task name" ["Note"] ["YYYY-MM-DD"]

Examples:

osascript -l JavaScript scripts/add_task.js "Buy groceries"
osascript -l JavaScript scripts/add_task.js "Review doc" "Check sections 1-3"
osascript -l JavaScript scripts/add_task.js "Submit report" "Q1" "2026-01-31"

Returns: Task ID

Listing Tasks

osascript -l JavaScript scripts/list_tasks.js [filter] [limit]

Filters:

• inbox - Inbox tasks
• available - Available (unblocked) tasks (default)
• flagged - Flagged tasks
• due-soon - Due within 3 days
• overdue - Past due
• all - All incomplete tasks

Returns: JSON array with task details (name, id, note, dueDate, flagged, project, tags)

Searching Tasks

osascript -l JavaScript scripts/search_tasks.js "keyword" [limit]

Searches task names and notes. Case-insensitive.

Returns: JSON array of matching tasks

Completing Tasks

osascript -l JavaScript scripts/complete_task.js "Task name"

Searches inbox first, then all tasks. Completes first match.

Updating Tasks

osascript -l JavaScript scripts/update_task.js "Task name" [--note "text"] [--due "YYYY-MM-DD"] [--flag true/false]

Examples:

osascript -l JavaScript scripts/update_task.js "Review" --note "Added notes"
osascript -l JavaScript scripts/update_task.js "Submit" --due "2026-02-01"
osascript -l JavaScript scripts/update_task.js "Important" --flag true

Getting Statistics

osascript -l JavaScript scripts/get_stats.js

Returns: JSON with counts:

• total, incomplete, inbox
• flagged, overdue, dueSoon
• available, blocked

Usage Guidelines

When Responding to User Queries

1. List tasks before acting on them to confirm targets
2. Parse JSON output for structured processing
3. Present results in user-friendly format (not raw JSON)
4. Confirm operations before completing or modifying tasks
5. Handle errors gracefully (task not found, etc.)

Common Patterns

Daily Review:

# Statistics overview
osascript -l JavaScript scripts/get_stats.js

# What needs attention
osascript -l JavaScript scripts/list_tasks.js overdue
osascript -l JavaScript scripts/list_tasks.js due-soon

Task Queries:

# "What's in my inbox?"
osascript -l JavaScript scripts/list_tasks.js inbox

# "What are my next actions?"
osascript -l JavaScript scripts/list_tasks.js available 10

# "Show my flagged tasks"
osascript -l JavaScript scripts/list_tasks.js flagged

Task Management:

# "Add a task to call John"
osascript -l JavaScript scripts/add_task.js "Call John"

# "Find tasks about the project"
osascript -l JavaScript scripts/search_tasks.js "project"

# "Mark 'Buy milk' as complete"
osascript -l JavaScript scripts/complete_task.js "Buy milk"

# "Flag the review task"
osascript -l JavaScript scripts/update_task.js "Review" --flag true

Output Handling

Scripts return JSON for structured data. When presenting to users:

1. Parse the JSON
2. Format results clearly
3. Summarize counts and key information
4. Highlight urgent items (overdue, due soon)

Example response format:

Found 3 overdue tasks:
• Submit Q1 report (due Jan 20)
• Review contract (due Jan 23)
• Call vendor (due Jan 24)

And 5 tasks due in the next 3 days:
• [list tasks]

Would you like me to flag or update any of these?

Error Handling

Common errors:

• Task not found - Double-check name or search first
• No tasks - Empty result, report clearly
• Invalid date - Use YYYY-MM-DD format
• OmniFocus not running - Scripts require OmniFocus

Multi-Step Operations

Find then act:

# 1. Search for task
RESULTS=$(osascript -l JavaScript scripts/search_tasks.js "meeting")

# 2. Parse and identify target task name

# 3. Complete the task
osascript -l JavaScript scripts/complete_task.js "Team meeting notes"

Technical Reference

For detailed API information and advanced usage, see:

• JXA API Reference: references/jxa-api.md - Object model and methods
• Automation Guide: references/automation-guide.md - Detailed script documentation and workflows

Read these files when:

• Building complex queries
• Understanding OmniFocus data model
• Implementing custom workflows
• Debugging scripts

Requirements

• macOS
• OmniFocus installed and running
• Scripts have execute permissions (chmod +x)

Notes

• Scripts use JXA (JavaScript for Automation), not AppleScript
• Task matching is case-sensitive for exact names, case-insensitive for searches
• Date format: YYYY-MM-DD (ISO 8601)
• All operations are performed on the default OmniFocus document
• Scripts are read-only safe except for add, complete, and update operations