Things Plus

Use the things CLI to read from and write to the local Things 3 database.

Credential policy: THINGS_AUTH_TOKEN may be required for some operations in some environments (for example, certain update paths). Verify token presence via things auth; do not ask the user to paste it into chat.

Setup

• - Install: INLINECODE3
• Ensure the install directory is on PATH.
• INLINECODE5 must be set in the environment visible to the execution context (prefer ~/.zshenv over ~/.zshrc for background/agent use).
• Grant Full Disk Access to the calling app only if database reads fail or direct DB access is needed.

Pre-flight

Run full pre-flight only on: explicit setup intent, or execution failures that suggest environment/auth/CLI issues. Do not block ordinary task capture on pre-flight.

CODEBLOCK0

Decision flow:

1. 1. App missing → stop; ask user to install Things.app
2. CLI missing or broken → stop; reinstall via Homebrew
3. INLINECODE8 fails → do not block ordinary add/read flows that still work directly; only pause token-gated operations and guide token setup if the requested action actually depends on token/auth (Things 3 → Settings → General → Things URLs). Verify presence with things auth in the same execution context before continuing
4. Auth present → proceed; do not treat things auth alone as proof writes work — verify with a real add/delete on a disposable item if write reliability is in question

Token setup: identify the active shell/context first (echo $SHELL), then give one exact command for the appropriate environment file. Prefer replacing an existing entry over appending a duplicate. Before asking the user about setup/auth/environment problems, first inspect the current execution context and try the smallest safe command that can confirm the actual behavior.

Interface layer

Use the things CLI as the execution interface.

Most common reads:

• - INLINECODE13
• INLINECODE14
• INLINECODE15
• INLINECODE16

Most common writes:

• - INLINECODE17
• INLINECODE18
• INLINECODE19

Use the smallest command that can safely confirm the current state.
Before risky mutations, prefer search and show to identify the exact item.
Verify every write by read-back instead of trusting exit status alone.

Execution rules

• - add: execute directly; no dry-run required
• INLINECODE23: use --dry-run first when the change is broad or risky
• INLINECODE25: for clearly identified single-item deletions, execute directly (recoverable via trash) and verify by read-back; for ambiguous or broad deletions, clarify first
• Prefer UUID for mutations whenever available; do not rely on title-only matching when an exact UUID can be obtained
• Never claim success from exit code alone — verify every write with a read

Duplicate prevention

Before add, do a quick duplicate check when the task title is generic or was mentioned earlier in the session:

CODEBLOCK1

If an open match exists, prefer updating by UUID. If intent is ambiguous, ask one brief clarifying question.

Strategy layer

• - Treat concrete personal planning phrases as capture intent; add directly without asking for confirmation
• For ambiguous intent (hypotheticals, someone else's plans, general discussion) — do not capture
• When the user mentions multiple distinct future actions in one message, split them into separate tasks unless they clearly belong to a single bundled action
• Use Things' native Today / Upcoming / Anytime / Someday views; do not invent extra taxonomy
• Only proactively surface Today + nearest Upcoming by default
• Rewrite titles for executability by default; preserve exact wording only when the user asks, the title is already action-ready, or verbatim capture is the point.
• When plans change, suggest re-prioritization; ask before moving anything to tomorrow

Field policy

--when

Use for any concrete or fuzzy time reference.

• - Exact time → INLINECODE28
• Fuzzy → morning 08:30 · noon 12:00 · afternoon 15:00 · evening 20:00 · before bed INLINECODE33
• Date only → INLINECODE34
• States → today · tomorrow · evening · anytime · INLINECODE39

--deadline

Use for latest acceptable completion date ("by Friday", "due Monday"). Not a substitute for --when. Set both when both apply.

--tags

Add only when tags clearly improve retrieval. Default: 0–2 tags. Reuse existing tags; do not invent new ones.

--checklist-item

Add only when the task has 2+ concrete sub-steps executed as a bundle. Max 5 items.

--repeat

Use for recurring personal tasks in Things (weekly reviews, habit reminders, etc.). Use cron for background/system automation. Do not infer recurrence unless the user asks.

Default workflow

For new task capture, always follow this order:

1. 1. infer intent
2. rewrite the title into an executable action
3. decide the correct view or schedule
4. add the task
5. verify by read-back

Do not add first and rewrite later unless the user explicitly asks to preserve exact wording.

1. Rewrite vague titles into executable actions

Before creating a task, rewrite vague, exploratory, or topic-like titles into the next visible executable action whenever possible. Do not preserve the user's original wording if it is too vague to act on directly.

Treat titles as needing rewrite if they are mainly about:

• - learning something broadly
• understanding a topic without a concrete output
• looking into, exploring, or checking something without a defined action or decision
• reviewing a resource without a clear next step
• naming a topic area rather than an action

If the title still reads like a topic, intention, or area of study rather than an action, rewrite it again before adding.

Examples:

• - buy groceries → INLINECODE46
• INLINECODE47 → INLINECODE48
• INLINECODE49 → INLINECODE50
• INLINECODE51 → INLINECODE52
• INLINECODE53 → INLINECODE54
• INLINECODE55 → INLINECODE56

2. Rewrite learning and research tasks toward a concrete next action

For learning, research, review, or exploration requests, convert broad titles into a concrete next action.

Prefer titles that describe:

• - reading or reviewing a specific resource
• extracting key points
• writing notes or a short summary
• comparing whether a resource is worth following
• outlining the basic concepts or framework

3. Route to the correct view

• - Today → clearly for today
• Upcoming → has a date/deadline/near-term commitment
• Anytime → important but unscheduled
• Someday → ideas, reading lists, later-maybe

4. Apply metadata deliberately

Only set --when, --deadline, --tags, or --checklist-item when the user's input actually warrants it. Default is a clean, simple task.

5. Daily report / logbook capture

When the user asks for a daily summary, work log, end-of-day report, or asks to summarize what was done today and put it into Things:

• - default to one completed todo with a concise title for the day or theme, plus a short checklist of the main outcomes
• use multiple completed todos only when the day clearly contains several unrelated threads
• summarize from available session context or memory instead of asking the user to restate the whole day unless key details are missing
• treat the day as a small number of themes, not a raw transcript
• preserve outcomes, decisions, validations, and deliverables; skip micro-steps
• if writing after midnight, warn the user it will land in the current day's Logbook

Error handling

Start with: INLINECODE61

• - If output is empty or fails to parse:
• run INLINECODE62
• if that is still broken, report CLI/database trouble

• - If things auth is empty:
• enter token setup flow only for operations that actually depend on token/auth
• do not block ordinary add/read flows that still work directly

• - If a UUID is not found:
• re-run things search to relocate the exact item

• - If a write appears to succeed but the data is unchanged:
• trust the read-back, not the exit status
• check in this order:

1. 1. token/auth requirement for that specific operation
2. shell/environment visibility
3. Things URL permission

• - If delete reports success but the item still appears:
• retry after a short pause
• suspect AppleScript instability before assuming auth failure

Recovery: never create a replacement task because an update failed. Fix auth/UUID first, then retry the original operation.

Tone

• - Direct and calm
• Collaborative triage, not productivity doctrine
• Explain before postponing; ask before moving to tomorrow