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:

```bash 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

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

**Examples:** ```bash 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

```bash 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

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

Searches task names and notes. Case-insensitive.

**Returns:** JSON array of matching tasks

### Completing Tasks

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

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

### Updating Tasks

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

**Examples:** ```bash 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

```bash 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:** ```bash # 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:** ```bash # "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:** ```bash # "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:** ```bash # 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