omnifocus_read

Query OmniFocus data with flexible filtering. Returns tasks, projects, tags, perspectives, folders, or exports.

COMMON QUERIES:

• Inbox: { query: { type: "tasks", filters: { project: null } } }

• Tasks in a specific project (by ID, fast): { query: { type: "tasks", filters: { projectId: "" } } }

• Overdue: { query: { type: "tasks", mode: "overdue" } }

• Today perspective: { query: { type: "tasks", mode: "today" } }

• Flagged: { query: { type: "tasks", mode: "flagged" } }

• Upcoming (7 days): { query: { type: "tasks", mode: "upcoming", daysAhead: 7 } }

• Smart suggestions: { query: { type: "tasks", mode: "smart_suggest", limit: 10 } }

• Count only (fast): { query: { type: "tasks", filters: { flagged: true }, countOnly: true } }

• Export tasks: { query: { type: "export", exportType: "tasks", format: "json" } }

MODES (tasks queries ONLY — not valid on type:"projects"):

• today: Due soon (≤3 days) OR flagged, matching OmniFocus Today perspective

• overdue: Tasks past their due date

• flagged: Flagged tasks

• upcoming: Tasks due in next N days (set daysAhead, default 14)

• inbox, available, blocked, search, smart_suggest, all

• To SEARCH projects (or tasks) use filters, not mode: filters: { name: { contains: "..." } } or filters: { text: { matches: "regex" } }

FILTER OPERATORS:

• tags: { any: [...] } (has any), { all: [...] } (has all), { none: [...] } (has none)

• dates (dueDate, deferDate, plannedDate, added): { before: "YYYY-MM-DD" }, { after: "..." }, { between: ["...", "..."] }

• text: { contains: "..." }, { matches: "regex" }

• boolean: flagged, blocked, available, inInbox

• logic: { OR: [...] }, { AND: [...] }, { NOT: {...} }

RESPONSE CONTROL:

• Default returns minimal fields (id, name, flagged, completed, dueDate, deferDate, tags, project, available)

• details: true returns all fields with full notes

• fields: [...] returns exactly those fields (note truncated to 200 chars unless details: true)

• ID lookup always returns all fields with full notes

• fields are type-specific; requesting a field of the other type (e.g. reviewInterval on tasks) returns a guided error

• fields (tasks): id, name, completed, flagged, blocked, available, estimatedMinutes, dueDate, deferDate, plannedDate, completionDate, added, modified, dropDate, note, projectId, project, tags, repetitionRule, parentTaskId, parentTaskName, inInbox

• fields (projects): id, name, status, flagged, note, dueDate, deferDate, completionDate, folder, folderPath, folderId, sequential, lastReviewDate, nextReviewDate, reviewInterval, defaultSingletonActionHolder, tags, plannedDate

• sort: [{ field: "dueDate", direction: "asc" }]

• limit/offset: Pagination (default limit: 25, max: 500)

• countOnly: true returns only count (33x faster for "how many" questions) — tasks only

COMPLETED TASKS:

• Use filters: { completed: true } or filters: { status: "completed" } to query completed tasks

• includeCompleted is for export operations only (type: "export"); honored by exportType: "tasks" and exportType: "all"

EXPORT TO DISK:

• outputDirectory: when set with exportType: "tasks", writes tasks. to disk (raises the implicit cap to 5000); required for exportType: "all"

• A response-path export (no outputDirectory) caps at 1000 by default and emits summary.truncated when the cap fires; override with limit

PERFORMANCE:

• Use countOnly for counting questions

• Use fields to select only needed data

• Use modes instead of raw filters when available

• Default queries are token-efficient (9 fields, no notes)