shared-things

Sync a Things 3 project between multiple macOS users

Stop duplicating todos manually. shared-things keeps your team's Things 3 project in sync via a lightweight self-hosted server—perfect for shared shopping lists, family tasks, or team todos.

Quick Start

Client (each user)

npm install -g shared-things-daemon
shared-things init

That's it. Follow the prompts.

Features

• 🔄 Real-time sync - Changes propagate within 30 seconds
• 🏠 Self-hosted - No cloud subscription, host on your own server
• 👥 Multi-user - Each person gets their own API key
• 🤫 Background daemon - Auto-starts on login, runs silently
• 🛠️ Interactive CLI - Easy setup wizard for configuration

Prerequisites

• macOS with Things 3 installed
• Node.js >= 18
• A server running shared-things-server (see Server Setup)

Usage

Interactive Mode

shared-things init

? Server URL: https://things.yourdomain.com
? API Key: ****
? Project name in Things: Shared Project
? Things auth token: ****

Note: The Things project must be empty when you run init.

Things auth token: Required for syncing updates to existing todos. Find it in Things → Settings → General → Things URLs → Enable Things URLs.

After Setup

shared-things start     # Start daemon (auto-runs on login)
shared-things status    # Check sync status
shared-things logs -f   # Follow sync logs

All Commands

| Command | Description | |---------|-------------| | init | Setup wizard | | start | Start launchd daemon (auto-starts on login) | | stop | Stop launchd daemon | | status | Show sync status & last sync time | | sync | Force immediate sync | | logs [-f] | Show logs (-f to follow) | | conflicts [--all] | Show conflict history | | repair | Diagnose state issues (no auto-fix) | | reset --local | Clear local state | | reset --server | Clear server data for this user | | doctor | Comprehensive health check |

Server Setup

One person hosts the server. Everyone else just needs an API key.

# Install
npm install -g shared-things-server

# Create a user (generates API key)
shared-things-server create-user
# → User "alice" created. API key: sk_abc123...

# Start server
shared-things-server start -d --port 3334

Server Commands

| Command | Description | |---------|-------------| | start [-d] [-p port] | Start server (-d for background) | | stop | Stop background server | | status | Show server status | | logs [-f] | Show logs (-f to follow) | | create-user | Create user and generate API key | | list-users | List all users | | delete-user | Delete a user | | reset | Delete all todos (keeps users) |

systemd Service

sudo tee /etc/systemd/system/shared-things.service << 'EOF'
[Unit]
Description=shared-things sync server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/shared-things-server start --port 3334
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now shared-things

HTTPS with Caddy

things.yourdomain.com {
    reverse_proxy localhost:3334
}

What Syncs

| Synced | Not Synced | |--------|------------| | Todo title, notes, due date, tags, status | Checklist items | | | Headings, Areas |

Note: The project must exist in each user's Things app. Only items within that project sync.

How It Works

Things User A ←→ Daemon A ←→ Server ←→ Daemon B ←→ Things User B

Each daemon polls Things every 30 seconds via AppleScript, pushes changes to the server, and pulls updates to apply via Things URL Scheme. Server is the single source of truth (last write wins).

Development

git clone https://github.com/yungweng/shared-things.git
cd shared-things
pnpm install
pnpm build

Contributing

Issues and PRs welcome! See open issues.

Links

• Repository
• Issues
• npm (daemon)
• npm (server)

Author

Maintained by @yungweng

License

MIT