things-todo

---
name: things-todo
description: "Use when working with things 3 via things CLI: add, list, search, update, delete, verify from steipete/agent-scripts."
source: https://github.com/steipete/agent-scripts/tree/main/skills/things-todo
generated: 2026-05-27T20:56:45.517Z
category: tool
audience: general
---

## When to use

- Things 3 tasks on Peter's Macs. Prefer things for Things-backed todos; use $reminders only when the user asks for Apple Reminders.
- Using the things-todo skill's upstream workflow, guardrails, and local-tool assumptions.
- Auditing commands or operational steps before changing things todo behavior.
- Needing a compact agent reference for things 3 via things CLI: add, list, search, update, delete, verify.

## Key concepts

### Start

Use JSON for scripted reads and verification: Things DB reads may need Full Disk Access for the calling app. Writes should go through Things URL Scheme or AppleScript via things; do not write the SQLite DB directly.

### Add

Default: add, then search/read back. Useful flags: --notes "text" --when today|tomorrow|evening|anytime|someday|YYYY-MM-DD --deadline YYYY-MM-DD --list "Project or Area" --tags tag1,tag2 --checklist-item "text" repeatable --dry-run to inspect the things:/// URL without mutating.

### Update / Delete

Find the UUID first, then mutate by id: Always read back after writes. Delete moves items to Things Trash; verify normal search is empty and trash search contains the item when cleanup matters.

### Conventions

Turn vague asks into concrete next-action titles. Preserve wording when the user clearly wants capture, not rewriting. Split unrelated actions into separate to-dos. Use Today only when the user implies it; otherwise use Inbox/Anytime defaults. Prefer --dry-run before bulk updates/deletes. For current date math, run date; do not guess.

### Gotchas

macOS only; remote hosts may show Things.app version as UNKNOWN if the app is absent or not visible there. update needs THINGSAUTHTOKEN; add does not. --tags is plural for add/update; tasks --tag is singular for filtering. today JSON may show start: Anytime plus a real startdate; use command membership/read-back, not one field alone, to verify Today placement.

## API reference

```
npx skills add steipete/agent-scripts --skill things-todo
```

Install the things-todo skill from steipete/agent-scripts.

```
npx skills add steipete/agent-scripts --skill things-todo
```

```
GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest.
```

Command or snippet documented by the upstream things-todo skill.

```
GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest
```

```
source ~/.profile >/dev/null 2>&1 || true.
```

Command or snippet documented by the upstream things-todo skill.

```
source ~/.profile >/dev/null 2>&1 || true
things auth
```

```
things tasks --format json --limit 20.
```

Command or snippet documented by the upstream things-todo skill.

```
things tasks --format json --limit 20
things today --format json
things search "query" --format json
```

```
things add "Book LHR-SFO nonstop business flight" --notes "Nonstop only." --when tomorrow --tags travel.
```

Command or snippet documented by the upstream things-todo skill.

```
things add "Book LHR-SFO nonstop business flight" --notes "Nonstop only." --when tomorrow --tags travel
things tasks --search "LHR-SFO" --format json
```

```
things tasks --search "flight" --format json.
```

Command or snippet documented by the upstream things-todo skill.

```
things tasks --search "flight" --format json
things update --id <uuid> "New title" --notes "Updated notes"
things tasks --search "New title" --format json
things delete --id <uuid> --confirm <uuid>
things tasks --search "New title" --format json
things trash --search "New title" --format json
```

## Gotchas

- Always read back after writes. Delete moves items to Things Trash; verify normal.
- Prefer --dry-run before bulk updates/deletes.

---
Generated by SkillMake from https://github.com/steipete/agent-scripts/tree/main/skills/things-todo on 2026-05-27T20:56:45.517Z.
Verify against source before relying on details.

File: ~/.claude/skills/things-todo/SKILL.md