A full-featured command-line interface and MCP server for Things 3 on macOS. Designed to be a daily driver for humans and a first-class tool for AI agents (Claude Code, GPT, etc.).
thingsctl review --days 7
thingsctl today --tag Deep --json
thingsctl complete 7Ae 17j 9pU
thingsctl template "Launch" --name "Launch Q3"
Plus — thingsctl-mcp exposes the same surface as native tools to any MCP client.
npm install -g thingsctlRequires macOS with Things 3 installed and Node ≥ 18.
Modifying tasks (add, complete, update, …) needs your Things URL auth token. Get it from Things → Settings → General → Enable Things URLs → Manage, then:
thingsctl config set-token <your-token>(Or set the THINGS_AUTH_TOKEN environment variable.)
thingsctl today # Today
thingsctl today --tag Deep # Filter by tag
thingsctl today --area Work # Filter by area
thingsctl today --json # Structured JSON
thingsctl inbox
thingsctl anytime
thingsctl someday
thingsctl upcoming
thingsctl due # All deadlines
thingsctl overdue # Past their deadline
thingsctl evening # "This evening" tasks
thingsctl repeating --decode # Recurrence + next instance
thingsctl logbook --since 7 # Completed in last 7 days
thingsctl projects
thingsctl project "Wedding"
thingsctl areas
thingsctl tags
thingsctl search "groceries"
thingsctl show 7Ae # Partial UUID — errors on ambiguity
thingsctl statsthingsctl add "Buy milk"
thingsctl add "Trip prep" --checklist "Passport,Tickets,Charger"
thingsctl add "Tax filing" --when 2027-04-15 --deadline 2027-04-15 --tags Important
thingsctl update 7Ae --title "New title" --append-notes "context"
thingsctl complete 7Ae # Single (to-do or project)
thingsctl complete 7Ae 17j 9pU # Bulk
thingsctl move 7Ae --to "next week" # RESCHEDULES; does not change project/area
thingsctl tag 7Ae --add Urgentmove reschedules. To change what a to-do or project belongs to, use update.
Things exposes different parameters for the two, and mixing them up is refused
rather than silently dropped:
thingsctl update 7Ae --list "Berlin Trip" # to-do → project or area, by title
thingsctl update 7Ae --list-id Xm55Bsr1Wmk # to-do → project or area, by uuid
thingsctl update p01 --area "Travel" # project → area, by title
thingsctl update p01 --area-id 7U6P28t2BfE # project → area, by uuidthingsctl review --days 7 # Weekly review (completed/added/deadlines)
thingsctl review --days 30 --json
thingsctl export today --format md > today.md
thingsctl export project "CoStudy" --format csv
thingsctl template "Sprint Template" --name "Sprint 12" # Clone a project
thingsctl template "Sprint" --dry-run # Preview JSON payload
thingsctl watch # Stream task changes as NDJSON
thingsctl watch --interval 10 --events completionsRegister the MCP server with Claude Code:
claude mcp add things thingsctl-mcpThen ask Claude things like "What's overdue?", "Add 'Schedule dentist' for tomorrow", "Run a weekly review", "Clone the Sprint Template project as Sprint 13" — Claude will call the appropriate tools (things_overdue, things_add, things_review, things_clone_project) directly.
The full MCP tool surface (24 tools): things_today, things_inbox, things_anytime, things_someday, things_upcoming, things_due, things_overdue, things_evening, things_repeating, things_logbook, things_projects, things_project, things_areas, things_tags, things_search, things_show, things_stats, things_review, things_export, things_add, things_update, things_complete, things_move, things_tag, things_clone_project.
- UUID prefix collisions are now an error (was: silently picked the first match). Pass
--yes-firstto opt into the old behavior on bulk commands. - N+1 query in filtered lists is gone — filters are pushed into SQL via JOINs, so
thingsctl today --tag Deepno longer fires hundreds of queries. - Cocoa-epoch math is centralized in
src/lib/dates.js(was inconsistent betweenlogbookandstats). export todaynow matchestoday— the same dedupe and Someday-exclusion runs.- CSV is RFC 4180 — quotes embedded
",,,\n,\rcorrectly. - Auth token is no longer in source — moved to
~/.config/thingsctl/auth-tokenorTHINGS_AUTH_TOKENenv.
- Reads open the Things 3 SQLite database in read-only mode at
~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/ThingsData-C1ON7/Things Database.thingsdatabase/main.sqlite. - Writes go through the Things URL scheme, the only officially-supported programmatic write path.
| Field | Values | Meaning |
|---|---|---|
todayIndex |
> 0 |
Task is in Today |
start |
0 / 1 / 2 |
Inbox / Anytime / Someday |
startBucket |
0 / 1 |
Today / This Evening |
startDate |
unix seconds | Scheduled date |
deadline |
unix seconds | Deadline |
stopDate |
Cocoa seconds | Completion timestamp |
creationDate |
Cocoa seconds | Created at |
userModificationDate |
Cocoa seconds | Last modified |
- Cannot create tags — they must already exist in Things.
- Cannot create headings — must already exist in projects.
- Cannot move to Inbox — URL scheme limitation.
- Cannot remove tags individually — would replace all tags.
- Things must be running for write operations.
git clone https://github.com/kaufmanhenry/thingsctl.git
cd thingsctl
npm install
npm run fixture # Build test SQLite fixture
npm test # Jest unit + integration
node bin/thingsctl.js todayReleases publish from CI via npm trusted publishing
(OIDC). There is no npm token stored anywhere — npm trusts
.github/workflows/publish.yml in this repo specifically, and each publish uses a
short-lived credential. Provenance is attached automatically.
npm version <patch|minor|major> --no-git-tag-version
# update CHANGELOG.md, commit, merge to main, then:
git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.ZPushing the tag is the release. The workflow refuses to publish if the tag and
package.json version disagree.
Two things that will break publishing if you change them:
- Renaming
publish.yml. npm pins the workflow filename; a rename fails withENEEDAUTHuntil the trusted publisher is reconfigured on npmjs.com. - Changing
repository.urlinpackage.json. It must match this GitHub repo exactly, or npm rejects the OIDC publish.
MIT