Things3 stores its data in a local SQLite database. We perform read-only access exclusively; all write operations are performed via URL Scheme.

Official Warning: Cultured Code has explicitly stated that direct database access is an "unsafe integration method" that may cause data corruption. We strictly read only.

# v3.15.16+ (current version)
~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/ThingsData-*/Things Database.thingsdatabase/main.sqlite

# v3.15.15 and earlier
~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/Things Database.thingsdatabase/main.sqlite

• Use the environment variable THINGSDB to override the default path
• Connection must use read-only mode: ?mode=ro
• Current database version: 26 (check via SELECT value FROM Meta WHERE key = 'databaseVersion'; things.py requires >=24)

The database has 15 tables in total, categorized by importance:

This is the most central table, storing all to-dos, projects, and headings.

Things3 uses two different time encoding methods:

Most queries filter with rt1_recurrenceRule IS NULL; recurring tasks require separate handling.

Tags are associated via TMAreaTag.

Tags support hierarchical structure: The parent field implements a tag tree. For example, "Places" can have child tags "Home" and "Office".

TMTask.contact references this table for the task delegation/associated contact feature.

User-defined smart lists; the definition field contains the filter rules.

SELECT uriSchemeAuthenticationToken FROM TMSettings WHERE uuid = 'RhAzEf6qDxCD5PmnZVtBZR'

Used to track deleted objects during Things Cloud sync.

Currently known key-value pairs:

• databaseVersion = 26
• didRemoveOrphanHeadings = true
• didCreateDefaultTags = true

This is the most distinctive technical detail of Things3. Dates and times do not use standard formats; instead they use bit-shift encoding.

Bit layout: YYYYYYYYYYYMMMMDDDDD0000000
- Y (bit 16-25): year value, left-shifted 16 bits
- M (bit 12-15): month value, left-shifted 12 bits
- D (bit 7-11):  day value, left-shifted 7 bits
- 7 trailing zero bits

Example: 2021-03-28

year = 2021, month = 3, day = 28
encoded = (2021 << 16) | (3 << 12) | (28 << 7)
        = 132382720 + 12288 + 3584
        = 132464128
binary: 0000 0111 1110 0101 0011 1000 0000 0000

Bit layout: hhhhhmmmmmm00000000000000000000
- h (bit 26-30): hour value, left-shifted 26 bits
- m (bit 20-25): minute value, left-shifted 20 bits
- 20 trailing zero bits

Example: 12:34

encoded = (12 << 26) | (34 << 20) = 840957952

-- Things date -> ISO date
CASE WHEN startDate IS NOT NULL THEN
  printf('%04d-%02d-%02d',
    (startDate >> 16) & 2047,    -- year
    (startDate >> 12) & 15,      -- month
    (startDate >> 7) & 31)       -- day
END

-- Things time -> ISO time
CASE WHEN reminderTime IS NOT NULL THEN
  printf('%02d:%02d',
    (reminderTime >> 26) & 31,   -- hour
    (reminderTime >> 20) & 63)   -- minute
END

When a to-do's deadline has passed and it appears in the Today list, the user can choose to "dismiss" it (not wanting to deal with it today). At that point, Things sets deadlineSuppressionDate to the current date, removing the task from the Today list until Things is reopened or the date changes and it is re-evaluated.

This field is critical for correctly computing the Today list (see below).

The Today list is not a single database field; it is the dynamic result of three parts combined:

-- Incomplete tasks with start = Anytime and a startDate
SELECT * FROM TMTask
WHERE status = 0 AND trashed = 0
  AND start = 1              -- Anytime
  AND startDate IS NOT NULL  -- has a start date
  AND rt1_recurrenceRule IS NULL
ORDER BY todayIndex

Tasks that were scheduled in the past but moved to Someday — Things shows a yellow dot to prompt the user to confirm:

-- start = Someday and startDate is in the past
SELECT * FROM TMTask
WHERE status = 0 AND trashed = 0
  AND start = 2                                    -- Someday
  AND startDate IS NOT NULL
  AND startDate < <today_as_things_date>           -- past date
  AND rt1_recurrenceRule IS NULL
ORDER BY todayIndex

Tasks with a past deadline but no startDate, unless the user has already dismissed them:

-- no startDate + deadline has passed + not suppressed
SELECT * FROM TMTask
WHERE status = 0 AND trashed = 0
  AND startDate IS NULL
  AND deadline IS NOT NULL
  AND deadline < <today_as_things_date>            -- overdue
  AND (deadlineSuppressionDate IS NULL
       OR deadlineSuppressionDate < <today_as_things_date>)  -- not suppressed
  AND rt1_recurrenceRule IS NULL

The results from all three parts are merged and sorted by todayIndex and startDate.

When a project or heading is trashed, the trashed field on its child to-dos may still be 0. Be aware of this when querying:

-- Exclude tasks whose parent has been trashed (context_trashed = False)
SELECT t.* FROM TMTask t
LEFT JOIN TMTask p ON t.project = p.uuid
LEFT JOIN TMTask h ON t.heading = h.uuid
WHERE t.trashed = 0
  AND (p.uuid IS NULL OR p.trashed = 0)
  AND (h.uuid IS NULL OR h.trashed = 0)

SELECT uuid, title, notes, status, start
FROM TMTask
WHERE type = 0              -- to-do
  AND status = 0            -- incomplete
  AND trashed = 0
  AND rt1_recurrenceRule IS NULL
ORDER BY "index"

SELECT t.uuid, t.title, t.status
FROM TMTask t
WHERE t.project = '<project-uuid>'
  AND t.trashed = 0
ORDER BY t."index"

SELECT t.uuid, t.title, GROUP_CONCAT(tag.title, ', ') as tags
FROM TMTask t
LEFT JOIN TMTaskTag tt ON t.uuid = tt.tasks
LEFT JOIN TMTag tag ON tt.tags = tag.uuid
WHERE t.type = 0 AND t.status = 0 AND t.trashed = 0
GROUP BY t.uuid

-- Get all tags and their parents
SELECT t.uuid, t.title, t.shortcut, p.title as parent_title
FROM TMTag t
LEFT JOIN TMTag p ON t.parent = p.uuid
ORDER BY t."index"

SELECT a.uuid, a.title, GROUP_CONCAT(tag.title, ', ') as tags
FROM TMArea a
LEFT JOIN TMAreaTag at ON a.uuid = at.areas
LEFT JOIN TMTag tag ON at.tags = tag.uuid
WHERE a.visible = 1
GROUP BY a.uuid
ORDER BY a."index"

SELECT uuid, title,
  untrashedLeafActionsCount as total_tasks,
  openUntrashedLeafActionsCount as open_tasks,
  (untrashedLeafActionsCount - openUntrashedLeafActionsCount) as done_tasks
FROM TMTask
WHERE type = 1 AND status = 0 AND trashed = 0

SELECT uuid, title,
  checklistItemsCount as total_items,
  openChecklistItemsCount as open_items
FROM TMTask
WHERE type = 0 AND checklistItemsCount > 0 AND trashed = 0

# TMTask.type
TYPE_TO_DO    = 0
TYPE_PROJECT  = 1
TYPE_HEADING  = 2

# TMTask.status
STATUS_INCOMPLETE = 0
STATUS_CANCELED   = 2
STATUS_COMPLETED  = 3

# TMTask.start
START_INBOX    = 0
START_ANYTIME  = 1
START_SOMEDAY  = 2

1. Read-only access: Never write to the database; all modifications are performed via URL Scheme
2. Date encoding: Things dates use a custom binary format, not standard Unix timestamps — they must be decoded correctly
3. NULL handling: Many fields use NULL to represent "not set"; be mindful of this when querying
4. Database lock: Things.app holds a database lock while running; use read-only mode to avoid conflicts
5. Path wildcard: The path for v3.15.16+ includes ThingsData-* and requires glob matching
6. Recurring tasks: Most scenarios should filter out recurring tasks (rt1_recurrenceRule IS NULL)
7. Context trashing: When a parent is trashed, child tasks may still have trashed = 0; use a JOIN to check
8. Tag hierarchy: TMTag.parent supports nested tags; consider the hierarchy when querying
9. Cached counts: The *Count fields are caches maintained by Things and can be used directly for progress display
10. Sync tables: Sync-related tables such as TMTombstone and BSSyncronyMetadata are for Things Cloud use only and do not need to be read by us