/things-setup

name: things-setup
description: "Connect Things 3 (macOS only) so Dex reads and updates your Things tasks. Use when the user says 'I use Things', 'sync my Things inbox', or pastes a `things://` link. Not for Todoist (`todoist-setup`) or Trello (`trello-setup`)."
manifest:
  id: things
  auth: none
  category: task_access
  platform: macos
  mcp_server: things3-mcp

Things 3 Setup

Connect Things 3 so Dex can work with your Things tasks whenever you ask. No account needed. Everything stays on your Mac. Works offline.

**What this enables (on request):** Once connected, say "sync with Things" — Dex pushes new tasks to the right Things Area (mapped from your pillars), marks completions via AppleScript, and pulls tasks you completed or added to Things Inbox. Everything stays local — no network calls, no accounts. Sync runs on demand when you ask.

What This Enables

Once connected, you can ask Dex to:

• **See your Things lists:** "What's in my Things Today list?" — including alongside your daily plan
• **Create there instead:** "Put that in Things, not Dex" in any conversation
• **Complete from chat:** "Mark the deck task done in Things"
• **Cross-check:** "Anything in Things that isn't tracked in Dex?"

Privacy

• Everything is local. Things 3 uses AppleScript — no cloud API, no tokens, no accounts
• Dex reads and writes Things only when you ask. Nothing leaves your machine
• No credentials to store. No tokens to expire. No OAuth flows
• Works completely offline

When to Run

• User types `/things-setup`
• User asks about connecting Things 3
• User wants Dex working with a Mac-native task app
• During `/integrate-mcp` if Things is mentioned
• During onboarding if user mentions Things 3

---

Setup Flow

Step 1: Platform Check

Things 3 is macOS only. Verify:

1. Check if running on macOS (`process.platform === 'darwin'` or `uname` check) 2. **If not macOS:**

   Things 3 is a macOS-only app. It won't work on this platform.

   For a cross-platform task app connection, consider:
   - /todoist-setup (works everywhere)
   - /trello-setup (web-based)

Stop here.

Step 2: Check if Already Connected

1. Read `System/integrations/config.yaml` 2. If `things.enabled: true`, skip to **Step 7** (Reconfigure) 3. If not configured, continue

Step 3: Check if Things 3 is Installed

Run a quick AppleScript test:

osascript -e 'tell application "System Events" to (name of processes) contains "Things3"'

Or check if the app exists:

ls /Applications/Things3.app 2>/dev/null || ls "$HOME/Applications/Things3.app" 2>/dev/null

**If Things 3 is not found:**

I can't find Things 3 on your Mac.

Things 3 is available from the Mac App Store:
https://apps.apple.com/app/things-3/id904280696

Once installed, run /things-setup again.

Stop here.

**If found:**

Things 3 detected. This is the simplest integration to set up — no accounts or API keys needed.

Everything stays on your Mac and works offline. Ready?

Wait for confirmation.

Step 4: Add the things3-mcp Server

Check the user's MCP configuration. If `things3-mcp` is not listed:

1. Explain:

I need to add the Things 3 connector to your Dex configuration.

This uses a lightweight AppleScript bridge — no accounts, no API keys.
It talks directly to Things 3 on your Mac.

2. Add to the user's `.mcp.json`:

{
  "things3-mcp": {
    "command": "npx",
    "args": ["-y", "things3-mcp"],
    "env": {}
  }
}

3. Tell the user the MCP server needs to restart for changes to take effect.

Step 5: Test the Connection

Run a quick test to verify AppleScript access:

1. List Things Areas:

   osascript -e 'tell application "Things3" to get name of areas'

2. List Things Projects:

   osascript -e 'tell application "Things3" to get name of projects'

**If macOS prompts for AppleScript permission:**

macOS is asking for permission to control Things 3. Click "OK" to allow.

This is a one-time prompt. Things 3 uses AppleScript for local communication —
no network access is involved.

**Show results:**

Connection test passed.

Your Things 3 setup:
- Areas: [list of areas]
- Projects: [list of projects]

If the test fails, jump to Troubleshooting.

Step 6: Configure Mapping

First, read `System/pillars.yaml` and extract the user's pillar `id` and `name` fields. If pillars are empty/not yet configured, prompt the user to run `/quarter-plan` first.

Map Dex pillars to Things Areas:

Now let's map your Dex pillars to Things Areas.

Your Dex pillars (from System/pillars.yaml):
[list each pillar name, numbered]

Your Things Areas:
[list from Step 5]

I'll suggest a mapping — adjust if needed:

| Dex Pillar | Things Area |
|------------|-------------|
| [pillar 1 name] | [best match or "[pillar 1 name]"] |
| [pillar 2 name] | [best match or "[pillar 2 name]"] |
...

Does this mapping look right? I can create any missing Areas in Things.

If areas don't exist, offer to create them (run once per missing pillar):

osascript -e 'tell application "Things3" to make new area with properties {name:"[pillar name]"}'

Step 7: Save Configuration

Write to `System/integrations/config.yaml` — update the things section. Build `area_mapping` dynamically from the user's pillars: use each pillar's `id` as the key and the confirmed Things Area name as the value (used when the user asks Dex to file something in Things under the right Area).

things:
  enabled: true
  configured_at: YYYY-MM-DD
  mcp_server: things3-mcp
  auth_type: none
  area_mapping:
    [pillar_id]: [Things Area name]   # one entry per pillar

If the file already exists, only update the `things:` section. Preserve other integration configs.

Step 8: Capability Cascade

Now that Things is connected, highlight what changes:

Things 3 is connected.

Here's what you can do now:

- **Ask about Things anytime** — "What's in my Tod