playbooks

home / skills / openclaw / openclaw / things-mac

things-mac skill

/skills/things-mac

This skill helps you manage Things 3 via the macOS CLI, enabling add, update, and read operations on tasks and projects.

This is most likely a fork of the mh-things-mac skill from openclaw
npx playbooks add skill openclaw/openclaw --skill things-mac

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.5 KB
---
name: things-mac
description: Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database). Use when a user asks OpenClaw to add a task to Things, list inbox/today/upcoming, search tasks, or inspect projects/areas/tags.
homepage: https://github.com/ossianhempel/things3-cli
metadata:
  {
    "openclaw":
      {
        "emoji": "✅",
        "os": ["darwin"],
        "requires": { "bins": ["things"] },
        "install":
          [
            {
              "id": "go",
              "kind": "go",
              "module": "github.com/ossianhempel/things3-cli/cmd/things@latest",
              "bins": ["things"],
              "label": "Install things3-cli (go)",
            },
          ],
      },
  }
---

# Things 3 CLI

Use `things` to read your local Things database (inbox/today/search/projects/areas/tags) and to add/update todos via the Things URL scheme.

Setup

- Install (recommended, Apple Silicon): `GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest`
- If DB reads fail: grant **Full Disk Access** to the calling app (Terminal for manual runs; `OpenClaw.app` for gateway runs).
- Optional: set `THINGSDB` (or pass `--db`) to point at your `ThingsData-*` folder.
- Optional: set `THINGS_AUTH_TOKEN` to avoid passing `--auth-token` for update ops.

Read-only (DB)

- `things inbox --limit 50`
- `things today`
- `things upcoming`
- `things search "query"`
- `things projects` / `things areas` / `things tags`

Write (URL scheme)

- Prefer safe preview: `things --dry-run add "Title"`
- Add: `things add "Title" --notes "..." --when today --deadline 2026-01-02`
- Bring Things to front: `things --foreground add "Title"`

Examples: add a todo

- Basic: `things add "Buy milk"`
- With notes: `things add "Buy milk" --notes "2% + bananas"`
- Into a project/area: `things add "Book flights" --list "Travel"`
- Into a project heading: `things add "Pack charger" --list "Travel" --heading "Before"`
- With tags: `things add "Call dentist" --tags "health,phone"`
- Checklist: `things add "Trip prep" --checklist-item "Passport" --checklist-item "Tickets"`
- From STDIN (multi-line => title + notes):
  - `cat <<'EOF' | things add -`
  - `Title line`
  - `Notes line 1`
  - `Notes line 2`
  - `EOF`

Examples: modify a todo (needs auth token)

- First: get the ID (UUID column): `things search "milk" --limit 5`
- Auth: set `THINGS_AUTH_TOKEN` or pass `--auth-token <TOKEN>`
- Title: `things update --id <UUID> --auth-token <TOKEN> "New title"`
- Notes replace: `things update --id <UUID> --auth-token <TOKEN> --notes "New notes"`
- Notes append/prepend: `things update --id <UUID> --auth-token <TOKEN> --append-notes "..."` / `--prepend-notes "..."`
- Move lists: `things update --id <UUID> --auth-token <TOKEN> --list "Travel" --heading "Before"`
- Tags replace/add: `things update --id <UUID> --auth-token <TOKEN> --tags "a,b"` / `things update --id <UUID> --auth-token <TOKEN> --add-tags "a,b"`
- Complete/cancel (soft-delete-ish): `things update --id <UUID> --auth-token <TOKEN> --completed` / `--canceled`
- Safe preview: `things --dry-run update --id <UUID> --auth-token <TOKEN> --completed`

Delete a todo?

- Not supported by `things3-cli` right now (no “delete/move-to-trash” write command; `things trash` is read-only listing).
- Options: use Things UI to delete/trash, or mark as `--completed` / `--canceled` via `things update`.

Notes

- macOS-only.
- `--dry-run` prints the URL and does not open Things.

Overview

This skill manages Things 3 on macOS using the things CLI and the Things URL scheme. It can read from the local Things database (inbox, today, upcoming, projects, areas, tags) and create or update todos via safe URL commands. Use it to add tasks, search or list items, and modify existing todos programmatically from an assistant workflow.

How this skill works

Read operations call the local Things database through the things CLI to list inbox, today, upcoming, projects, areas, tags, or to run text searches. Create and update operations build Things URL commands (or call the CLI) so Things opens or receives a command; updates require an auth token for write actions. For safety, dry-run mode prints the generated URL without opening Things; DB reads may require Full Disk Access for the calling app.

When to use it

  • Add a new todo quickly from a chat or voice command (title, notes, project, tags).
  • List or search existing tasks: inbox, today, upcoming, or free-text search.
  • Inspect project, area, or tag lists to show structure before taking action.
  • Update an existing todo (title, notes, move to project/heading, tags, complete or cancel).
  • Automate recurring imports or capture flows into Things from other tools on macOS.

Best practices

  • Use --dry-run to preview URL commands before opening Things to avoid accidental changes.
  • Set THINGS_AUTH_TOKEN for scripts that perform updates to avoid passing tokens on the command line.
  • Grant Full Disk Access to the calling app (Terminal or gateway app) if DB reads fail.
  • Prefer moving items by update (list/heading) and mark complete/canceled rather than deleting.
  • Specify project/heading and tags explicitly to ensure items land in the right context.

Example use cases

  • Capture: Add a quick inbox task: things add "Buy milk" with optional notes and tags.
  • Planning: List today or upcoming to present a daily plan generated by the assistant.
  • Migration: Bulk-search tasks and move them into a new project or heading via update commands.
  • Edit: Find a todo by search, then update title or append notes using the todo's UUID and auth token.
  • Checklist creation: Create a task with checklist items piped from STDIN for multi-line content.

FAQ

Does this work on Windows or Linux?

No — Things 3 and this CLI are macOS-only.

How do I perform safe writes during automation?

Use --dry-run to preview the URL or set THINGS_AUTH_TOKEN and test with a non-destructive update (e.g., append notes) before running bulk changes.