things-agent

things-agent

Go CLI to drive Things (macOS) through AppleScript only, built with cobra.

See AGENTS.md for project operation rules (session-start backup, retention, safety, conventions).

Project status

This repository started as a fast prototype built in one day with Codex (gpt-5.3-codex-spark xhigh), and then continued with gpt-5.3-codex high, using Go + AppleScript + Things URL Scheme.

• It is responsive and already useful in practice using spark.
• It works well with voice workflows (for example with MacWhisper).
• It is primarily a proof of concept, not a fully hardened product yet.
• It still needs cleanup, more refactoring, stronger safety checks, and broader tests.

The project is validated for Codex and Claude Code today. It should also be usable from other local-agent setups (for example Cline), but those integrations have not been fully validated yet.

For Claude Code, the convention is to read instructions from CLAUDE.md, while this project keeps AGENTS.md as the source of truth. The recommended setup is to create a symlink so both tools read exactly the same instructions:

ln -sf AGENTS.md CLAUDE.md

AI Agent Usage

This repository is intended to work with both Codex and Claude Code.

• Codex reads AGENTS.md directly.
• Claude Code uses CLAUDE.md.
• Keep a single source of truth by symlinking:

ln -sf AGENTS.md CLAUDE.md

Prerequisites

• macOS
• Things app installed
• osascript

The CLI never accesses the Things SQLite database directly. Some native checklist operations (URL scheme update) require a Things auth token (THINGS_AUTH_TOKEN or --auth-token). Default target list is Inbox (English Things UI). List names are localized by Things, so use the exact name from your own app language.

Examples:

• English UI: Inbox
• French UI: À classer

If your Things language is not English, set:

export THINGS_DEFAULT_LIST="À classer"

Or pass --list explicitly on each command.

Installation

Install from tags (recommended):

go install github.com/alnah/things-agent@latest

Install the unstable version (latest main):

go install github.com/alnah/things-agent@main

Releases are built from v* tags with GoReleaser.

Hybrid setup for AI agents required

For this project, installation is intentionally hybrid:

• go install gives you the executable.
• git clone gives your AI agent the repository context (AGENTS.md, docs, workflows, security constraints).

Using only one of the two is not enough for the intended Codex/Claude workflow.

Security warning read before use

Use this project at your own risk.

Agent Risk Model

• To be useful, AI agents often need broad system permissions.
• Agents can bypass expectations or instructions if they are sufficiently capable.
• This repository includes safety rails, but not a full safety harness.
• You remain fully responsible for what the agent executes on your machine.

Safety personal choice

• Emptying Things trash is intentionally not exposed by the CLI.
• This is a deliberate safety decision to avoid irreversible bulk deletion by script.
• Deletion remains available item by item (delete-task, delete-project, delete-list) with backup beforehand.
• session-start backup is required in agent instructions before state-changing operations.
• Backups are rotated and capped at 50 snapshots (about ~7 MB each on the author's machine).
• AGENTS.md explicitly forbids direct SQLite access.
• Bypassing CLI constraints through alternative command paths requires explicit user decision and responsibility.

Auth Token Handling

Do not expose your Things auth token to your AI provider unless strictly necessary.

Get the token on macOS:

1. Open Things 3.
2. Go to Things -> Settings -> General.
3. In the Things URLs section, open token management and copy the auth token.
4. Export it in your shell:

export THINGS_AUTH_TOKEN="<your-token>"

A practical approach is to store the token with pass and only resolve it locally in shell config:

# example pattern
export THINGS_AUTH_TOKEN="$(pass show things/auth-token)"

This reduces accidental exposure, but it is not a perfect guarantee. If an agent is allowed and motivated to exfiltrate secrets, it may still leak the token.

Setup for AI Agents

Use this checklist before running the project with Codex or Claude Code:

git clone https://github.com/alnah/things-agent.git
cd things-agent

go install github.com/alnah/things-agent@main
# optional runtime env (example for French Things setup)
export THINGS_DEFAULT_LIST="À classer"

# required for URL update/checklist operations
export THINGS_AUTH_TOKEN="<your-things-token>"

# keep one instruction source for Codex + Claude Code
ln -sf AGENTS.md CLAUDE.md

# quick health check
things-agent version
things-agent session-start

Usage

things-agent session-start
things-agent backup
things-agent tasks --list "À classer"
things-agent search --query "Wagner"
things-agent add-task --name "Say hello" --notes "Message" --list "À classer"
THINGS_DEFAULT_LIST="À classer" things-agent add-task --name "Uses env default list"
things-agent add-task --name "Native checklist" --subtasks "Point 1, Point 2" --auth-token "<token>"
things-agent complete-task --name "Say hello"
things-agent list-subtasks --task "Say hello"
things-agent add-subtask --task "Say hello" --name "Review the message"
things-agent tags list
things-agent tags search --query "work"
things-agent tags add --name "urgent"
things-agent tags edit --name "urgent" --new-name "high-priority"
things-agent tags delete --name "high-priority"
things-agent url add --title "URL task" --tags "test"
things-agent url update --id "<todo-id>" --append-checklist-items "one, two" --auth-token "<token>"

Useful Commands

URL Scheme API Mapping