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