Things 3 Task Manager

Interact with Things 3, the user's personal task manager for Mac.

Quick Start

Read operations: Use TypeScript with esbuild to write type-safe JXA code via scripts/run-jxa.sh Write operations: Use things:// URL schemes (things:///add, things:///update, things:///json) Auth token: security find-generic-password -a "$USER" -s "things-auth-token" -w (see @1password.md for setup)

Common Commands

Read today's todos:

scripts/run-jxa.sh 'const app = Application("Things3"); const today = app.lists.byId("TMTodayListSource"); JSON.stringify(today.toDos().map(t => ({id: t.id(), name: t.name()})), null, 2);'

Create a todo:

open "things:///add?title=Task%20name&when=today&tags=Work"

Update a todo:

auth_token=$(security find-generic-password -a "$USER" -s "things-auth-token" -w)
open "things:///update?id=ABC-123&auth-token=$auth_token&append-notes=Additional%20info"

Navigate to today:

open "things:///show?id=today"

Built-in List IDs

• TMInboxListSource - Inbox
• TMTodayListSource - Today
• TMNextListSource - Anytime
• TMCalendarListSource - Upcoming
• TMSomedayListSource - Someday
• TMLogbookListSource - Logbook

When Values

• today, tomorrow, evening
• anytime, someday
• yyyy-mm-dd (specific date)
• Natural language: "in 3 days", "next week"

Status Values (JXA)

• open - Active todo
• completed - Completed
• canceled - Canceled

Documentation

Load detailed guides as needed:

• setup.md - TypeScript/JXA development setup, array conversion, running scripts
• examples.md - Comprehensive usage examples for all operations
• jxa.md - Complete JXA object model and API reference
• url-scheme.md - URL scheme commands and parameters
• 1password.md - Auth token setup and keychain configuration
• troubleshooting.md - Common issues, best practices, repeating task detection

Essential Tips

• URL encoding: Always URL-encode parameters (spaces → %20, newlines → %0a)
• Verification: ALWAYS verify updates succeeded by reading back the todo with JXA
• Repeating tasks: Filter by comparing creationDate to midnight (see troubleshooting.md)
• TypeScript mode: Use scripts/run-jxa.sh for type-safe JXA with autocomplete