things:jxa ยท diff
git:20260702.25323d3 to git:20260708.bedc98e
1 added, 1 removed. Audit A to A.
---
name: things:jxa
- description: Read and query Things 3 data (lists, todos, projects, tags, logbook). Not for writes. Use things:url to create/update, things:inbox for quick captures.
+ description: Read and query Things 3 data (lists, todos, projects, tags, logbook). Not for writes. Use things:url to create, update, or capture to the inbox.
allowed-tools:
- "Bash(bun ${CLAUDE_PLUGIN_ROOT}/scripts/format-output.ts:*)"
- "Skill(mac:jxa-run)"
- "Skill(mac:jxa-run Things3:*)"
- Read
---
# Things JXA
Read and query Things 3 data via JXA.
## Running JXA
To run JXA, use the Skill tool to invoke `mac:jxa-run`. Do NOT run `bun` or `osascript` directly.
#### Script file
Invoke via: `Skill(mac:jxa-run, args: "Things3 ${CLAUDE_PLUGIN_ROOT}/scripts/jxa/query-list.js TMTodayListSource")`
#### Inline expression
Invoke via: `Skill(mac:jxa-run, args: "Things3 -e 'var app = Application(\"Things3\"); JSON.stringify(app.lists.byId(\"TMTodayListSource\").toDos().length)'")`
#### Formatting output
Pipe the returned JSON through the formatter for table display:
```bash
echo '<json>' | bun ${CLAUDE_PLUGIN_ROOT}/scripts/format-output.ts [--json] [--columns name,status]
```
## Scripts
| Script | Usage | Description |
|--------|-------|-------------|
| `find-todos.js` | `<tag\|project> <name> [--logbook]` | Find todos by tag (across Inbox/Today/Anytime/Upcoming/Someday) or project |
| `query-list.js` | `<list-id>` | Query todos from any built-in list |
| `query-logbook.js` | `<start-iso> <end-iso> [--notes-contains <substring>]` | Query logbook with early termination. Full scans of 10k+ items are slow. `--notes-contains` filters by notes substring and includes `notes` in output (e.g. to find `Discovery:` markers). |
| `query-metadata.js` | `<projects\|areas\|tags>` | List projects, areas, or tags (tags omit todoCount for performance) |
| `export-markdown.js` | `[list-id]` | Export a list to markdown checklist |
## Built-in List IDs
`TMInboxListSource` (Inbox), `TMTodayListSource` (Today), `TMNextListSource` (Anytime), `TMCalendarListSource` (Upcoming), `TMSomedayListSource` (Someday), `TMLogbookListSource` (Logbook)
## Repeating Tasks
Detect via midnight heuristic: `creationDate` at `T00:00:00` local time = repeating instance. Templates have `activationDate: null`. See [troubleshooting.md](troubleshooting.md) for examples.
## Status Values
`open`, `completed`, `canceled`
## Reference
- [jxa.md](jxa.md): Object model and API
- [setup.md](setup.md): Development setup
- [troubleshooting.md](troubleshooting.md): Common issues
## Tips
- Use `properties()` for batch reads instead of individual getters
- `open -g -a "Things3"` to launch Things if not running