Things3 Pages

Mirror the Things3 Inbox, projects, and areas as editable Markdown notes in Obsidian.

Things3 Pages is an unofficial, macOS-only community plugin. It is not affiliated with or endorsed by Cultured Code. Things is a trademark of Cultured Code GmbH.

What it does

• Links an ordinary Markdown note to the Things Inbox, a project, or an area.
• Synchronises task titles, task notes, completion states, headings, checklists, project notes, and container names in both directions.
• Links projects in an area page to their existing project pages.
• Preserves Markdown outside the managed section.
• Resolves simultaneous edits deterministically using the last successful synchronisation as a baseline.
• Keeps writes manual by default, with configurable automatic synchronisation when wanted.

Deleting a Things3 Pages note only removes the local link. It never deletes the corresponding project, area, or Inbox from Things.

Requirements

• macOS with Things3 installed.
• Obsidian desktop 1.5.0 or later.
• The companion Apple Shortcut for headings, task placement beneath headings, and checklist content.

Installation

Community Plugins

1. Open Settings → Community plugins in Obsidian.
2. Search for Things3 Pages.
3. Choose Install, then enable the plugin.

Manual installation

Download main.js, manifest.json, and styles.css from the matching GitHub release. Place them in:

<vault>/.obsidian/plugins/things-pages/

Reload Obsidian and enable Things3 Pages under Community plugins.

Install the companion Shortcut

1. Open Settings → Things3 Pages.
2. Choose Install shortcut.
3. Approve Things-Pages Helper in Apple Shortcuts.
4. Return to Obsidian and choose Verify shortcut.

The signed Shortcut is embedded in the plugin release. Installation always goes through Apple's normal approval screen; the plugin cannot install it silently.

Create a page

Choose the check-square ribbon button or run Link current note to Things Inbox, project, or area.

• If the active note is empty, it becomes the selected Things page.
• If the active note already contains text, a new page is created beside it.
• If no note is open, choose the Things container first and then choose a destination folder.

The page receives things3-id, things3-type, and things3-name properties. Use the ribbon button again, or run Synchronise current Things page, to synchronise it manually.

For an area page, existing project pages become Obsidian links. Run Create project page from current area to create a missing project page in a chosen folder. Projects and direct area tasks appear in separate Projects and Tasks sections, each retaining its order from Things.

Synchronised content

Changes made in Things are reflected in Markdown during the next synchronisation. Automatic filename changes follow the side renamed since the previous successful synchronisation.

Markdown outside the managed section remains untouched. The HTML comments inside the managed section hold stable Things identifiers; the plugin hides standalone marker lines in Obsidian's editor. Task notes use tab-indented blockquotes and checklist items are tab-indented so they fold beneath their parent task in Reading mode. A blank quoted line separates task notes from their checklist items.

Mobile editing

Things3 Pages is a desktop-only plugin and cannot be enabled on iPhone or iPad. A mirrored page remains an ordinary Markdown note on mobile, where its notes, tasks, and checklist items can still be edited.

Do not delete or alter the hidden <!-- things3:... --> identifier comments or <!-- things3-mirror:... --> section markers. They allow the desktop plugin to match Markdown lines to the correct Things items during the next synchronisation. Mobile edits can travel through the vault's normal synchronisation service. The designated Mac merges them with Things when Obsidian next runs and synchronises the page.

Automatic synchronisation

Automatic synchronisation is off by default. When enabled, choose an interval from one minute to one hour. The status bar shows the last successful synchronisation and the next scheduled attempt.

Automatic task, heading, or checklist deletions, project completion or cancellation, and ordering changes require the separate Allow sensitive automatic changes setting. Task deletion still needs two matching observations at least 30 seconds apart and moves the task only to Things Trash. If Things reports open tasks, completing or cancelling their project is always deferred to manual synchronisation and an explicit confirmation. If a linked project page contains an unfinished task that is not synchronised with Things, the project status change is blocked until that page is synchronised.

Use one Mac as the automatic synchronisation authority for a vault.

Permissions and local data access

Things3 Pages works locally and includes no telemetry or network requests.

• /usr/bin/osascript reads Things and performs supported task and container changes.
• /usr/bin/shortcuts runs the narrowly scoped companion helper.
• /usr/bin/sqlite3 -readonly reads checklist data for selected tasks, heading metadata, and the identity of projects already returned for an area.
• /usr/bin/open opens only the embedded Shortcut installation file.

macOS asks for Automation permission when Obsidian first communicates with Things. On newer macOS versions, mirrored pages may also require permission to read Things' app-group data. This is not Full Disk Access.

The database is never opened for writing. If its location, permission, or expected schema is unavailable, synchronisation stops safely. See Read-only Things database access, Security, and Community review notes for the complete scope and safeguards.

Limitations

• Existing Things headings cannot be reordered from Markdown.
• Exact task ordering uses an undocumented Things AppleScript command. It is experimental and off by default.
• The plugin does not create or delete Things projects or areas from Markdown.
• A completed or cancelled project leaves its active area page; reopen it in Things if needed.
• Version 0.1 assumes one Mac is responsible for automatic synchronisation.
• Things database schema changes may temporarily prevent pages from synchronising.

Development

npm install
npm run verify
npm run release:check

npm run verify checks Prettier, the official Obsidian ESLint rules, strict TypeScript, Vitest, and the production bundle. Live tests are opt-in because they create a disposable Things project:

npm run test:live:read
npm run test:live:write
npm run test:live:structured

Start with Architecture for the source map and synchronisation call chain. The Companion Shortcut document defines the complete JSON request contract.

The release contains only main.js, manifest.json, and styles.css. The readable companion source and signed Shortcut are retained in shortcuts/.

Licence

Things3 Pages is licensed under MIT. The maintainer-only Cherri compiler patch in shortcuts/cherri-951c0bb.patch is separately licensed under the GNU General Public License, version 2; see Third-party notices.