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
---

<!-- Generated from `.claude/skills/things-setup/SKILL.md` by `scripts/generate-agents-skills.py`. Do not edit. -->

# 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:

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

Or check if the app exists:

```bash
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`:

```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:
   ```bash
   osascript -e 'tell application "Things3" to get name of areas'
   ```

2. List Things Projects:
   ```bash
   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):

```bash
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).

```yaml
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 Today list?", "Put that in
  Things", "Mark the deck task done in Things"
- **Bring it into planning** — during /daily-plan, ask me to include your
  Things tasks and I will
- **Right Area, automatically** — when I file something in Things for you,
  your pillars map to your Things Areas
- **Sync on demand** — say "sync Dex with Things" and Dex pushes pending tasks, marks
  completions, and reviews anything new in your Things Inbox

No accounts. No tokens. No expiration. Works offline.

**Sync is on demand** — say "sync with Things" anytime. No background polling.
```

---

## Troubleshooting

### Things 3 Not Installed

Things 3 must be installed from the Mac App Store. It's a paid app (~$49.99).
Once installed, run `/things-setup` again.

### AppleScript Permission Denied

macOS may block AppleScript access. To fix:

1. Open **System Settings** > **Privacy & Security** > **Automation**
2. Find your terminal app (Terminal, iTerm2, etc.)
3. Enable the toggle for **Things3**
4. Retry the setup

### "Things3 got an error" Messages

Things 3 must be running for AppleScript to work. Open Things 3, then retry.

### Areas Not Showing

If no Areas appear during setup:

1. Open Things 3
2. Go to Settings > General
3. Make sure Areas are enabled
4. Create at least one Area, then retry

---

## Reconfiguration

If the user runs `/things-setup` when already configured:

1. Show current config from `System/integrations/config.yaml`
2. Offer options:
   - Update pillar-to-area mapping
   - Re-test the connection
   - Disconnect Things

### Disconnect Flow

If user wants to disconnect:

1. Update `System/integrations/config.yaml`:
   ```yaml
   things:
     enabled: false
   ```
2. Confirm: "Things 3 is disconnected. Tasks will no longer sync. Run `/things-setup` anytime to reconnect."