things3

things3-for-claude

A Claude Code plugin that lets Claude interact with Things 3 on macOS.

Use cases: GTD inbox grooming, weekly reviews, bulk filing, and archiving ideas — all via conversation.

How it works

• Reads query the local Things SQLite database directly (fast, no app interaction)
• Writes go through AppleScript — the officially supported automation path for Things 3
• Checklists use the Things URL scheme add command (no auth token needed)
• Safety: gzipped DB snapshot taken before every write; --expect-title verification on all UUID-targeting writes

Install

# In Claude Code, add this repo as a marketplace:
/plugin marketplace add amohield/things3-for-claude

# Then install the things3 skill:
/plugin install things3@things3-for-claude

On first write, macOS will prompt:

"Claude Code" wants to control "Things3". Allow?

Click OK. If you accidentally denied it: System Settings → Privacy & Security → Automation → Claude Code → Things3.

Usage

Once installed, just talk to Claude:

• "Groom my Things inbox"
• "Run a GTD weekly review"
• "What's in my Someday list?"
• "Move all items in project X to project Y"
• "Dump my Ideas area to a markdown file"

Claude will use the things3 skill automatically for Things-related requests.

CLI reference

The CLI is at plugins/things3/skills/things3/bin/things. See SKILL.md in that directory for the full command reference, or run:

python3 /path/to/skill/bin/things --help
python3 /path/to/skill/bin/things <command> --help

Safety

Every write takes a gzipped snapshot of the Things DB before making any change. If the snapshot fails, the write is aborted — no changes are made.

UUID-targeting writes (update, complete, cancel, reopen, trash) require --expect-title "Exact Title". The CLI verifies the title matches before mutating.

python3 bin/things list-backups        # see available snapshots
python3 bin/things restore             # guided DB restore (Things Cloud aware)
python3 bin/things history             # write audit log

Backups live at ~/.things3-claude/ (not committed — contains personal data).

Dev setup (bursty development)

# Clone
git clone https://github.com/amohield/things3-for-claude
cd things3-for-claude

# Switch to live-symlink dev mode (edits are immediately active in Claude Code)
bash scripts/dev-link.sh

# When done developing, restore plugin install
bash scripts/dev-unlink.sh

No dependencies to install — things.py is vendored at vendor/things/ (Apache-2.0, v1.0.1). The CLI runs on system Python 3 (3.7+).

Vendored dependency

things.py v1.0.1 is vendored at plugins/things3/skills/things3/vendor/things/. It is Apache-2.0 licensed (see vendor/things/LICENSE and vendor/things/NOTICE). It has no third-party runtime dependencies (pure stdlib + sqlite3). It is strictly read-only.

Known limitations

• --when evening: Things' Evening flag is not settable via AppleScript; the item is scheduled for today instead.
• Editing native checklists on existing todos: requires the Things URL auth token (out of scope). Use update --notes with markdown checkboxes as a workaround.
• Recurring tasks: not returned by default (things.py behavior).
• --move-to by name: first matching project/area wins. Rename to disambiguate if needed.

License

MIT — see LICENSE.

Vendored dependency vendor/things/ is Apache-2.0 (see vendor/things/LICENSE).