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.

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

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

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 (re-sync from server)
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)

Production Deployment

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