npm version license node version
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.
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.
- π 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
- macOS with Things 3 installed
- Node.js >= 18
- A server running
shared-things-server(see Server Setup)
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.
shared-things start # Start daemon (auto-runs on login) shared-things status # Check sync status shared-things logs -f # Follow sync logs
| 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 |
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
| 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
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
things.yourdomain.com {
reverse_proxy localhost:3334
}
| 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.
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).
git clone https://github.com/yungweng/shared-things.git
cd shared-things
pnpm install
pnpm buildIssues and PRs welcome! See open issues.
Maintained by @yungweng
MIT