OmniFocus

Manage OmniFocus tasks via JavaScript for Automation (JXA) scripts. Use when the user asks Clawdbot to interact with OmniFocus, including - (1) Adding tasks to inbox, (2) Listing or searching tasks (inbox, available, flagged, overdue, due soon), (3) Completing tasks, (4) Updating task properties (notes, due dates, flags), (5) Getting OmniFocus statistics, (6) Reporting on task status, or (7) Acting on tasks in OmniFocus based on user queries.

Security Scan

The skill's files, instructions, and requirements are coherent for automating OmniFocus via JXA; it performs only local OmniFocus operations and requests no unrelated credentials or installs.

Purpose & Capability

Name/description match the provided JXA scripts (add, list, search, complete, update, stats). The skill does not request unrelated environment variables, binaries, or services; required platform (macOS) and OmniFocus are appropriate and documented.

Instruction Scope

SKILL.md instructs running the included JXA scripts via osascript and to parse JSON output; it recommends confirming before modifying tasks. The references mention an optional direct SQLite database path for read-only access — the shipped scripts do not use that path, but the documentation could encourage a consumer to access the database directly. This is an informational note rather than an active behavior in the skill.

Install Mechanism

No install spec — instruction-only with bundled scripts. Nothing is downloaded or written by an installer. Scripts run locally via osascript, which is low-risk compared to remote installs.

Credentials

The skill requests no environment variables or credentials. It uses macOS automation APIs (Application('OmniFocus')) which is expected for the stated purpose. No unrelated secrets or system config paths are requested by the scripts.

Persistence & Privilege

always:false and user-invocable:true (normal). The skill can perform write actions (add, complete, update) on the user's OmniFocus data — expected for task-management. Because the platform allows autonomous invocation by default, consider the usual caution about granting automation permissions; however, this skill does not request permanent presence or modify other skills.

Assessment

This skill is internally consistent for controlling OmniFocus via JXA and does not reach out to the network or ask for credentials. Before installing or running it: (1) Verify you trust the skill author — source/homepage are not provided; review the script contents yourself (they're included) if you have any doubt. (2) Be aware macOS will require Automation permissions to let these scripts control OmniFocus — granting that gives the scripts local control over your OmniFocus data. (3) The scripts perform write operations (add/complete/update), so test on a small set or a copy/backup of your data if concerned about accidental changes. (4) The references mention a direct SQLite database path (read-only use case); the provided scripts do not access it, but direct DB access could expose more data and should be treated with care. (5) No network exfiltration or secret access was found in the code; still run in a controlled environment first if you have high sensitivity to data changes.

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