You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Go CLI to drive Things (macOS) through AppleScript and the Things URL Scheme, built with `cobra`, with a narrowly scoped internal SQLite step used only for restore.
9
+
> AI-first operational bridge for Things 3 on macOS. It gives an AI agent a constrained CLI over Things' existing automation surfaces: AppleScript, the official Things URL Scheme, and a narrowly scoped internal SQLite restore harness used only for restore workflows.
10
+
11
+
Independent project. Not affiliated with Cultured Code.
10
12
11
13
Documentation split:
12
14
13
15
-`README.md`: user-facing guide for the human who asks an AI coding agent such as Codex, Claude Code, Open Code, or similar tools to manage Things through the CLI.
14
16
-[`AGENTS.md`](./AGENTS.md): operator contract for the AI agent that actually runs the CLI.
15
17
16
-
## Project status
18
+
## Why this exists
19
+
20
+
Things already exposes useful automation surfaces, but AI agents benefit from a narrower operational layer with explicit commands, machine-readable outputs, and safer recovery workflows than ad hoc scripts.
21
+
22
+
This project is built for the practical path:
23
+
24
+
`Human intent -> AI agent -> things-agent CLI -> Things 3`
17
25
18
-
This repository started as a fast prototype built in one day with Codex (`gpt-5.3-codex-spark xhigh`), then used `gpt-5.4 high` to build out the codebase in Go with AppleScript and the Things URL Scheme.
26
+
Normal reads and writes stay on top of AppleScript and the official Things URL Scheme.
27
+
Internal SQLite work is reserved for restore only.
19
28
20
-
- It is primarily a proof of concept, not a fully hardened product yet.
21
-
- It works well with voice workflows (for example with MacWhisper).
22
-
- It is responsive and already useful in practice using spark.
23
-
- It still needs cleanup, more refactoring, stronger safety checks, and broader tests.
29
+
## What it does
30
+
31
+
- reads Things state in text or JSON forms that an AI agent can use reliably
32
+
- creates, edits, moves, completes, and deletes areas, projects, tasks, checklist items, and child tasks
33
+
- adds backup, restore, preflight, and verification flows for higher-risk operations
34
+
- keeps direct database access out of normal agent-authored operations
35
+
36
+
## Project status
37
+
38
+
- This project is primarily meant to be consumed by an AI agent, not used as a polished human-first CLI.
39
+
- It is already useful in practice for organizing Things through AI, including voice-driven workflows.
40
+
- It includes safety rails, backup/restore workflows, and verification steps, but it is not fully hardened.
41
+
- The user still takes real risk and will likely need to grant system permissions for the setup to work reliably.
24
42
25
43
## Installation
26
44
@@ -55,6 +73,29 @@ Some native checklist operations (URL scheme `update`) require a Things auth tok
55
73
Things uses both user areas and built-in lists (`Inbox`, `Today`, `Logbook`, etc.); this CLI uses `area` for the area entity and keeps `list` only for generic Things list filters and official URL parameters.
56
74
For token, permissions, and list-locale errors, see [Troubleshooting](#troubleshooting).
57
75
76
+
## Interaction model
77
+
78
+
The primary model is:
79
+
80
+
`Human -> AI agent -> things-agent CLI -> Things 3`
81
+
82
+
This repository is not trying to turn Things into a general-purpose shell app for direct human use.
83
+
The main goal is to give an AI agent a constrained operational bridge to read and change Things state with clearer semantics and some safety controls.
84
+
85
+
In practice, this means:
86
+
87
+
- the human expresses intent in natural language
88
+
- the AI agent translates that intent into `things-agent` commands
89
+
- the CLI uses AppleScript and the Things URL Scheme to operate Things 3
90
+
- backup, restore, and verification flows try to reduce risk, but do not remove it
91
+
92
+
## Design constraints
93
+
94
+
- normal operations use Things automation surfaces rather than direct database access
95
+
- restore is the only place where the project uses a narrowly scoped internal SQLite step
96
+
- the CLI is designed to be explicit enough for an AI agent to execute and verify safely
97
+
- permissions, local machine policy, and user trust still matter
98
+
58
99
## Using with Codex, Claude Code, Open Code, etc.
59
100
60
101
Use this checklist before asking an AI agent to manage Things for you:
@@ -78,18 +119,21 @@ things-agent version
78
119
things-agent --help
79
120
```
80
121
122
+
You usually do not need to drive the CLI manually beyond setup, debugging, or recovery.
123
+
The normal path is to let the AI agent read `AGENTS.md`, inspect `things-agent --help`, and then operate Things through the CLI.
124
+
81
125
## Domain glossary
82
126
83
127
Use these terms when talking to the agent. They match the CLI's high-level model from `things-agent --help`.
84
128
85
-
| Term | Meaning | Language alternatives |
86
-
| --- | --- | --- |
87
-
|`area`| A user-managed Things area. High-level CRUD and move commands use `area`. |`domaine`, `aire`, `área`, `Bereich`|
88
-
|`list`| A generic Things list name used for read filters and the official URL Scheme. This includes built-in lists such as `Inbox`, `Today`, `Logbook`, and `Archive`, plus area names where the Things API expects a generic list selector. |`liste`, `lista`, `Liste`|
89
-
|`project`| A Things project. |`projet`, `proyecto`, `projeto`, `Projekt`, `progetto`|
90
-
|`task`| A top-level to-do. |`tâche`, `tarea`, `tarefa`, `Aufgabe`, `attività`|
91
-
|`checklist item`| A lightweight native checklist line inside a task. |`élément de checklist`, `elemento de checklist`, `item de checklist`, `Checklistenpunkt`|
92
-
|`child task`| A structured child to-do under a project. |`sous-tâche`, `subtarea`, `subtarefa`, `Unteraufgabe`, `sottoattività`|
|`area`| A user-managed Things area. High-level CRUD and move commands use `area`. |`domaine`, `aire`, `área`, `Bereich`|
132
+
|`list`| A generic Things list name used for read filters and the official URL Scheme. This includes built-in lists such as `Inbox`, `Today`, `Logbook`, and `Archive`, plus area names where the Things API expects a generic list selector. |`liste`, `lista`, `Liste`|
133
+
|`project`| A Things project. |`projet`, `proyecto`, `projeto`, `Projekt`, `progetto`|
134
+
|`task`| A top-level to-do. |`tâche`, `tarea`, `tarefa`, `Aufgabe`, `attività`|
135
+
|`checklist item`| A lightweight native checklist line inside a task. |`élément de checklist`, `elemento de checklist`, `item de checklist`, `Checklistenpunkt`|
136
+
|`child task`| A structured child to-do under a project. |`sous-tâche`, `subtarea`, `subtarefa`, `Unteraufgabe`, `sottoattività`|
93
137
94
138
When in doubt:
95
139
@@ -137,7 +181,7 @@ Each snapshot also gets a small JSON index file (`timestamp`, `kind`, `created_a
137
181
138
182
## Common workflows
139
183
140
-
Ask the agent in natural language, for example:
184
+
Ask the AI agent in natural language, for example:
141
185
142
186
- "Show me what is in Today and Inbox."
143
187
- "Create a project in area Codebases and add three tasks."
@@ -152,8 +196,9 @@ Ask the agent in natural language, for example:
152
196
If AppleScript calls fail or the CLI cannot control Things, validate the environment first:
153
197
154
198
```bash
155
-
osascript -e 'tell application "Things3" to get name'
199
+
osascript -e 'tell application id "com.culturedcode.ThingsMac" to get name'
156
200
things-agent version
201
+
things-agent lists
157
202
```
158
203
159
204
Then re-check macOS privacy settings for your terminal/agent app:
@@ -171,7 +216,7 @@ If you see missing or invalid token errors:
0 commit comments