OmniFocus 4 Operations

Connect to OmniFocus 4 on macOS and perform authorized operations: list tasks, create tasks, complete tasks, check inbox, view flagged tasks, manage projects, contexts, perspectives, and more.

Prerequisites

• OmniFocus 4 must be installed on macOS
• OmniFocus must be running (the skill will prompt to launch if not)

Path Setup

BASE="${CLAUDE_PLUGIN_ROOT:-${CODEX_HOME:-$HOME/.codex}}"
SKILLS_ROOT="$BASE/skills"
[ -d "$SKILLS_ROOT/omnifocus/scripts" ] || SKILLS_ROOT="$BASE/indie-toolkit/mactools/skills"

Core Commands

Status Overview

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py status

List Tasks

# List all incomplete tasks (limit 20)
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py list

# List tasks in specific project
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py list "Project Name"

Inbox Tasks

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py inbox

Flagged Tasks

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py flagged

Due Tasks

# Due within 7 days (default)
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due

# Due within custom days
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due 14

# Due today
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due today

# Due tomorrow
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due tomorrow

# Due this week
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due week

# Overdue tasks
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due overdue

List Projects

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py projects

Contexts 上下文

List All Contexts

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py contexts

Set Task Context

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-context "Task Name" "Context Name"

Clear Task Context

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py clear-context "Task Name"

Due Dates 截止日期

Set Task Due Date

# Set with natural language
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-due "Task Name" "tomorrow"

# Set with relative format
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-due "Task Name" "+3d"

# Set with absolute date
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-due "Task Name" "2025-02-01"

Clear Task Due Date

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py clear-due "Task Name"

Defer Dates 开始日期

Set Task Defer Date

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-defer "Task Name" "+3d"

Clear Task Defer Date

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py clear-defer "Task Name"

Repetition Rules 重复规则

Set Task Repetition

# Daily
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-repeat "Task Name" "FREQ=DAILY"

# Weekly
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-repeat "Task Name" "FREQ=WEEKLY"

# Every 2 weeks
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-repeat "Task Name" "FREQ=WEEKLY;INTERVAL=2"

# Monthly
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-repeat "Task Name" "FREQ=MONTHLY"

Clear Task Repetition

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py clear-repeat "Task Name"

Note Operations 备注

Append Note to Task

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py append-note "Task Name" "Additional note text"

Task Operations

Create Task

# Create task in inbox
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py add "Task Name"

# Create task with options
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py add "Task Name" --project "Project" --context "Context" --due "tomorrow" --defer "+1d" --note "Task note"

# Create task with repetition
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py add "Daily Task" --repeat "FREQ=DAILY"

Complete Task

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py complete "Task Name"

Toggle Flag

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py flag "Task Name"

Delete Task

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py delete "Task Name"

Project Operations

Show Project Details

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py show-project "Project Name"

Create Project

# Create project in root
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py create-project "Project Name"

# Create project in folder
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py create-project "Project Name" "Folder Name"

Folder Operations

List All Folders

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py folders

Create Folder

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py create-folder "Folder Name"

Perspective Operations 透视

List All Perspectives

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py perspectives

Activate Perspective

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py activate-perspective "Perspective Name"

Date Formats 日期格式

Natural Language 自然语言

• 今天 / today - Today
• 明天 / tomorrow - Tomorrow
• 后天 - Day after tomorrow
• 下周 / next week - Next week

Relative Formats 相对格式

• +3d - 3 days from now
• +1w - 1 week from now
• +2m - 2 months from now (approx. 60 days)

Absolute Formats 绝对格式

• 2025-02-01 - ISO format
• 02/01/2025 - MM/DD/YYYY

⚠️ 仅支持 MM/DD/YYYY 格式，避免 DD/MM 歧义。遇到模糊日期（如 01/02）时，向用户确认。

Short Formats 短格式

• 02-01 - February 1st (current year, MM-DD)
• 02/01 - February 1st (current year, MM/DD)

Common Workflows

Daily Review

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py status
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py inbox
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py flagged
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due today

Weekly Review

python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py projects
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py contexts
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due week
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py due overdue

Quick Capture

# Quick add to inbox
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py add "Buy milk"

# Add with context and due date
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py add "Call John" --context "Phone" --due "tomorrow"

# Add recurring task
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py add "Daily standup" --project "Work" --repeat "FREQ=DAILY"

Context-Based Work

# List all contexts
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py contexts

# Start working in a context
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py activate-perspective "Context: Errands"

# Assign context to task
python3 ${SKILLS_ROOT}/omnifocus/scripts/omnifocus_cli.py set-context "Buy groceries" "Errands"

Troubleshooting

Issue	Solution
"OmniFocus is not running"	Launch OmniFocus first
"Project not found"	Check exact project name with projects command
"Context not found"	Check exact context name with contexts command
"Multiple matching tasks"	Use more specific task name
Task not found	Task may already be completed or deleted
"Invalid date"	Check date format against Date Formats section
"Invalid range"	Use: today, tomorrow, week, overdue

Limitations

• Requires OmniFocus 4 running on macOS
• Cannot modify completed tasks
• Project and context names must match exactly
• Task matching is case-insensitive but uses substring matching
• Repetition rules use OmniFocus's iCalendar syntax