ofocus (OmniFocus CLI)

ofocus is a Python CLI for OmniFocus on macOS. It talks to OmniFocus through JXA (JavaScript for Automation) via osascript. In other words, no plugins, no server, and no API keys are needed to run it.

• GitHub: https://github.com/yy/ofocus
• PyPI: https://pypi.org/project/ofocus/

Why#

OmniFocus doesn’t have a command-line interface or a local API. The only ways to interact with it programmatically on macOS are AppleScript and JXA. I wanted a simple CLI that lets me manage tasks from the terminal and, more importantly, one that AI coding agents like Claude Code can use as a tool. There are OmniFocus MCP implementations out there, but I prefer a lightweight CLI that agents invoke directly — no MCP overhead in the context window.

Install & use#

Since ofocus is on PyPI, the easiest way to run it is with uv:

# Run directly without installing
uvx ofocus stats
uvx ofocus inbox
uvx ofocus search "quarterly" --json

# Or install as a persistent tool
uv tool install ofocus
ofocus inbox add "Read paper" --due 2026-03-15 --flag

# Upgrade to latest
uv tool upgrade ofocus

What it does#

• Inbox: list and add tasks with notes, due dates, and flags
• Tasks: list active tasks filtered by project, tag, flagged status, or due date
• Search: find tasks by name or note across both inbox and active tasks
• Projects & tags: list, filter, and create projects
• Mutate: complete, update, drop, or delete tasks by ID
• Export: ofocus dump for a full JSON snapshot; ofocus stats for quick counts

Use with AI agents#

The easiest way to give an agent access is to run ofocus usage — it prints a full command reference that agents can read directly. No need to clone the repo or point at a URL. For example, in a CLAUDE.md:

For OmniFocus access, run `ofocus usage` to see available commands.

The same reference is also available as USAGE.md in the repo. Every command supports --json for structured output.