applescript-omnifocus
Skill8 starsChanged 8 months agoMITView on GitHub
Use when writing, modifying, or debugging ANY AppleScript that interacts with OmniFocus. Also use when encountering AppleScript errors, unexpected OmniFocus behavior, or when adding new connector methods. Covers variable naming traps, rich text limitations, recurring task handling, date formats, string escaping, and batch operation patterns.
In this repository5 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- api-designSkill
- integration-testingSkill
- performance-patternsSkill
- releaseSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Safe naming pattern: Always prefix with the entity type:
- Very specific: line 51
Use mark complete (the AppleScript command) for any task that might recur.
- Distinctive: line 87
When writing new date-handling code, always use the existing converter rather than building date strings manually.
- Distinctive: line 91
Always escape user-provided strings before embedding in AppleScript:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AppleScript + OmniFocus Patterns
This skill covers the hard-won knowledge about scripting OmniFocus via AppleScript. These are not obvious from documentation and have caused real bugs in this project.
Critical: Variable Naming Conflicts
OmniFocus AppleScript has a dangerous quirk: if you use a variable name that matches an OmniFocus property, AppleScript silently reads the property instead of your variable.
Bug-causing names (NEVER use as variables):
name, note, status, flagged, completed, sequential, due date, defer date, estimated minutes, repetition rule, repetition method
Safe naming pattern: Always prefix with the entity type:
-- BAD: "name" collides with OmniFocus property
set name to "My Task"
set name of theTask to name -- reads property of theTask, not your variable!
-- GOOD: prefixed variable name
set taskName to "My Task"
set name of theTask to taskName -- works correctlyReal bug from this project: A variable called status inside a tell task block caused OmniFocus to read the task's status property instead of the variable value, producing silent data corruption. The elifintervalDays typo story: unit tests passed because they mocked AppleScript, but integration tests against real OmniFocus caught the variable collision. This is why integration tests exist.
Rich Text Notes Limitation
OmniFocus stores notes as rich text internally. The AppleScript API exposes this inconsistently:
- Reading:
note of taskreturns plain text (stripped of formatting) - Writing:
set note of task to "text"replaces the entire note with plain text, destroying any rich text formatting
There is no workaround. You cannot preserve rich text through the AppleScript API. Document this to users and warn when overwriting notes.
Recurring Task Completion
Two ways to complete a task — only one handles recurrence correctly:
-- CORRECT: Creates next occurrence for recurring tasks
mark complete theTask
-- WRONG: Just marks this instance done, no next occurrence spawned
set completed of theTask to trueUse mark complete (the AppleScript command) for any task that might recur. Use set completed to true only when you specifically want to kill a recurring task's future occurrences.
The connector uses mark complete by default in update_task() when completed=True is passed.
JSON Construction in AppleScript
AppleScript has no native JSON support and no module system. Every AppleScript block that needs to return structured data must include inline JSON helper functions.
Current pattern (used 9x in the connector):
on escapeJSON(theText)
set resultText to ""
repeat with i from 1 to count of theText
set c to character i of theText
if c is "\"" then
set resultText to resultText & "\\\""
else if c is "\\" then
set resultText to resultText & "\\\\\\\\"
else
set resultText to resultText & c
end if
end repeat
return resultText
end escapeJSONThis duplication is intentional and necessary. Do not try to "DRY" it — AppleScript blocks must be self-contained because osascript -e executes each block independently.
Date Format Conversion
AppleScript uses locale-dependent date strings. The connector normalizes to ISO 8601:
- AppleScript format:
"March 5, 2026 5:00:00 PM" - ISO 8601 format:
"2026-03-05T17:00:00" - Conversion:
_iso_to_applescript_date()in the connector handles both directions
When writing new date-handling code, always use the existing converter rather than building date strings manually.
String Escaping
Always escape user-provided strings before embedding in AppleScript:
name_escaped = self._escape_applescript_string(name)
script = f'set name of theTask to "{name_escaped}"'The _escape_applescript_string() method handles quotes and backslashes. Without this, a task name containing " will break the AppleScript block silently.
Batch Operation Patterns
Single AppleScript call for multiple items is always faster than multiple calls:
-- GOOD: One call, N items (100-300ms total)
tell application "OmniFocus"
tell front document
repeat with t in flattened tasks
-- process all tasks in one block
end repeat
end tell
end tell
-- BAD: N calls, one item each (100-300ms PER call)
for task_id in task_ids:
script = f'tell application "OmniFocus" ... get task {task_id} ...'
run_applescript(script) # 100-300ms each!When batch is not possible: Some operations (like mark complete) must be done per-task because they trigger OmniFocus-internal workflows. In these cases, accept the overhead.
Error Handling Pattern
AppleScript errors should be caught in the script and returned as prefixed strings:
try
-- operation
return "SUCCESS"
on error errMsg
return "ERROR: " & errMsg
end tryThe Python side then checks for the prefix:
result = run_applescript(script)
if result.startswith("ERROR:"):
raise Exception(result)This is more reliable than catching subprocess.CalledProcessError, which doesn't always contain useful error messages from OmniFocus.
Database Safety System
The connector has a safety system that prevents destructive operations on production data:
- Requires
OMNIFOCUS_TEST_MODE=trueandOMNIFOCUS_TEST_DATABASE=OmniFocus-TEST.ofocus - Each destructive operation calls
_verify_database_safety()which runs an AppleScript to check the current database name - Operations tracked in
DESTRUCTIVE_OPERATIONSset: create, update, delete, reorder
This adds ~100ms per destructive call but prevents catastrophic data loss. Do not bypass it.
Integration Test Requirement
If you wrote or modified AppleScript in the connector, you MUST write or update integration tests before the PR is ready. Unit tests mock run_applescript() — they prove your Python logic works but say nothing about whether the AppleScript is valid. Offer to run make test-integration before creating the PR.
OmniFocus-Specific AppleScript Quirks
first flattened task whose id is X— works for tasks. Useflattened projectsfor projects,foldersfor folders.front documentvsdefault document—front documentis for UI operations,default documentfor data operations. Some operations require one or the other.- Focus — only projects and folders can be focused. Attempting to focus a task or tag raises an error.
- Perspectives — perspective names are accessed via
perspective names(plural), switching viaset perspective name of window to X. - Move operations —
move task to before/after referenceTaskrequires both tasks to be in the same project and at the same hierarchy level.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

