Skip to main content
Generalbendrucker

things:url

Create, update, and manage Things 3 tasks and projects. Not for reads — use things:jxa to query data. For simple inbox captures, use things:inbox.

Stars
13
Source
bendrucker/claude
Updated
2026-05-31
Slug
bendrucker--claude--url
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/bendrucker/claude/HEAD/plugins/things/skills/url/SKILL.md -o .claude/skills/url.md

Drops the SKILL.md into .claude/skills/url.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Things URL Scheme

Write operations for Things 3 via the things:/// URL scheme.

Quick Start

Use url.ts for most operations — it handles auth tokens and URL encoding:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/url.ts <command> [key=value ...]

# Bulk update: pass multiple id= params to batch via JSON command
bun ${CLAUDE_PLUGIN_ROOT}/scripts/url.ts update id=X id=Y id=Z when=tomorrow

For raw URL scheme access: open -g "things:///add?title=Buy%20milk&when=today"

Use -g for data commands (add, update, json) to run in background. Omit -g for show/search to foreground Things.

Commands

Command Description Auth required
add Create a todo No
add-project Create a project with optional todos No
update Modify a todo's properties Yes
update-project Modify a project's properties Yes
show Navigate to a list, todo, or project No
search Open search with optional query No
json Batch create/update via JSON payload Yes (for updates)

See examples.md for detailed usage of each command.

Reorder Items

bun ${CLAUDE_PLUGIN_ROOT}/scripts/reorder.ts [--list today|anytime|someday] <id1> <id2> <id3> ...

Items appear at the top of the list in the order specified. Default list is today. Also works for items within a project — use the --list value matching the items' current scheduling state.

Callback

When the x-callback-url plugin is installed, url.ts automatically uses xcall to get a response from Things on stdout. Present the result to the user as clickable https://things.bendrucker.me/show?id=<id> links:

  • Single todo (add, update): returns x-things-id=<id> — present one link
  • Batch (json): returns x-things-ids=["id1","id2"] — present a bulleted list with each todo's title and link

Callback is enabled by default. Disable with --callback=false to fall back to fire-and-forget via open -g. If xcall is unavailable, the script falls back silently.

Built-in List IDs (URL Scheme)

For show command: inbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects

Lookup Area IDs

The list parameter only works with project names. For areas, use list-id with the area UUID (query area IDs via the things:jxa skill).

When Values

  • today, tomorrow, evening
  • anytime, someday
  • yyyy-mm-dd (specific date)
  • Natural language: "in 3 days", "next week"

Notes Formatting

Things supports Markdown in notes:

  • Headings: #, ##, ###
  • Bold: **text**
  • Highlights: ::text::
  • Code: backticks for inline, triple backticks for blocks
  • Links: [title](url)
  • Lists: - or 1.

Documentation

  • examples.md — Detailed usage examples for all commands
  • url-scheme.md — Complete URL scheme commands and parameters
  • 1password.md — Auth token setup and keychain configuration

Tips

  • Moving out of inbox: Set when=anytime to move a todo out of inbox without assigning an area
  • Moving to area: Use list-id with the area UUID (not area-id)
  • Rate limiting: Max 250 operations per 10 seconds. For 3+ items, use multi-ID syntax (id=X id=Y id=Z) to batch into a single JSON command instead of individual calls.
  • Repeating todos: Cannot update when or deadline on repeating to-dos