Skip to content
Get packs

Guide · Agent skill

How to use the Things 3 CLI agent skill (things-mac)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The things-mac skill teaches an AI agent to work with Things 3, a to-do app on macOS, through a command-line tool called things. This guide explains what an agent skill is, how to install this one, how to ask for things in plain language, and what to check for safety. By the end you will be able to have an agent add tasks, search your lists and preview changes before they happen.

Things 3 CLIspinabot/brigade · MIT

Quick start

  1. 1Confirm your setup. Check that you are on macOS with Things 3 installed. Install a Go toolchain if you plan to use the recommended install.
  2. 2Install the things CLI. Run the go install command from the skill's setup section to install github.com/ossianhempel/things3-cli.
  3. 3Install the skill. Download the things-mac ZIP, unzip it into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
  4. 4Grant Full Disk Access. If database reads fail, grant Full Disk Access to Terminal or Brigade.app in macOS privacy settings.
  5. 5Make a read-only request. Ask the assistant what is on your Things list for today to confirm reads work.
  6. 6Preview a write. Ask for a task to be added and check the dry-run output before letting the change go ahead.

What is an agent skill and what does things-mac let the agent do?

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions and commands for one specific job. When a request matches the skill's description, the agent uses those instructions. This skill's description says it is for managing Things 3 via the things CLI on macOS.

Read-only access uses your local Things database. The agent can list your inbox, today and upcoming tasks, search tasks, and list projects, areas and tags. Write access uses the Things URL scheme, so the agent can add todos and projects and update existing todos.

  • Read: inbox, today, upcoming, search, projects, areas, tags
  • Write: add todos, add to a project or area, set notes, tags and checklists, update titles, notes, tags and lists, mark complete or canceled
  • Preview: a dry-run option prints the URL without opening Things

Install the things-mac skill (download, unzip and install the CLI)

First, download the things-mac ZIP from the skill page on this site and unzip it. Put the resulting things-mac folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder to limit it to that project. Alternatively, in the Claude apps, go to Settings → Capabilities → Skills and upload the skill there.

The skill also needs the things command-line tool. The source recommends installing it with Go on Apple Silicon Macs, which requires a Go toolchain. The module is github.com/ossianhempel/things3-cli, and the command below is the one given in the skill file.

  • Requires macOS and the Things 3 app installed
  • Requires a Go toolchain for the recommended install
  • If you do not use Apple Silicon, adjust GOBIN to match your system; the source only gives the Apple Silicon path
GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest

Grant permissions and set optional settings

Reading the local Things database requires Full Disk Access. If database reads fail, grant it to the app that runs the command: Terminal for manual runs, or Brigade.app for gateway runs. This is set in macOS privacy settings.

Two optional settings help. THINGSDB (or the --db flag) points the tool at your ThingsData-* folder. THINGS_AUTH_TOKEN saves you from passing --auth-token each time you update a task.

  • Full Disk Access: needed for database reads
  • THINGSDB or --db: point to your ThingsData-* folder
  • THINGS_AUTH_TOKEN: needed only for editing existing tasks

Trigger the skill with natural requests

You do not need to type commands yourself. Ask the assistant in plain language, using the kinds of requests the skill description covers: adding a task to Things, listing your inbox, today or upcoming tasks, searching tasks, or inspecting projects, areas and tags.

The skill's own examples show what the agent runs underneath. For example, adding a task with notes and a list uses the add command with --notes and --list. Adding from several lines uses standard input, where the first line becomes the title and the rest become notes.

  • 'Add a task to Things to book flights, in the Travel project'
  • 'What is on my Things list for today?'
  • 'Show my upcoming Things tasks'
  • 'Search Things for milk'
  • 'What tags do I have in Things?'
things inbox --limit 50 things today things upcoming things search "query" things add "Buy milk" --notes "2% + bananas" things add "Book flights" --list "Travel"

Edit existing tasks and preview changes safely

Editing an existing todo needs its ID. The agent gets it by searching first, then reads the UUID column from the results. Updates require an auth token, either set as THINGS_AUTH_TOKEN or passed with --auth-token.

The skill recommends a dry run before any write. The --dry-run flag prints the URL and does not open Things, so you can check what would happen. Use the same flag with add or update.

  • Find the task ID with a search first
  • Use --dry-run to preview the URL
  • Mark tasks done with --completed or drop them with --canceled
things search "milk" --limit 5 things --dry-run add "Title" things update --id <UUID> --auth-token <TOKEN> --completed

Safety notes: scripts, network and deletion

The skill runs scripts, which means the agent executes the things command on your Mac. The source says it does not use the network. Editing tasks needs an auth token, so store it carefully, because mishandling it could expose your task data.

The tool cannot delete tasks. The source says there is no delete or move-to-trash write command, and the trash command only lists items. To remove a task, delete or trash it in the Things app, or use update to mark it completed or canceled.

  • Limited to macOS (darwin) and Things 3 only
  • Scripts run: yes. Network use: no
  • Deletion is not supported by the CLI

What people use it for

  • Capture a task from a chat: ask the agent to add 'Call dentist' with the health and phone tags.
  • Get a morning summary: ask for today's and upcoming tasks without opening the app.
  • Find a task before changing it: search for a phrase, then mark that task completed.
  • Add a multi-line item with notes, such as a trip plan with a checklist of passport and tickets.
  • Review your projects, areas and tags to decide where a new task should go.

Frequently asked questions

Is the things-mac skill free?

The skill is released under the MIT licence, as listed for spinabot/brigade. The things CLI comes from github.com/ossianhempel/things3-cli, and you will need Things 3 installed on your Mac.

What do I need to use the Things 3 CLI agent skill?

You need macOS, the Things 3 app, the things CLI installed with Go, and a Go toolchain for the recommended install. Full Disk Access is needed for database reads, and THINGS_AUTH_TOKEN is optional but required for editing existing tasks.

Does it work on Windows or Linux?

No. The skill is limited to macOS (darwin) and Things 3 only, so it will not work on Windows or Linux.

Can the agent delete tasks in Things 3?

No. The things3-cli tool has no delete or move-to-trash write command, and its trash command only lists items. You can delete in the Things app, or mark a task completed or canceled with update.

Why does reading my Things data fail?

The skill says database reads may fail without Full Disk Access. Grant it to Terminal for manual runs or to Brigade.app for gateway runs, then try again.

How is this different from using the Things app directly?

The skill lets an AI agent read your Things data and make changes from a chat request. Editing still happens through Things' URL scheme, and the skill recommends previewing with --dry-run first.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose this skill if you use Things 3 on a Mac and want to add tasks or get quick summaries by asking an assistant. Pick something else if you use Windows or Linux, need the agent to delete tasks, or are not comfortable storing an auth token for edits.

Download the skill