{"id":35365615,"url":"https://github.com/yungweng/shared-things","last_synced_at":"2026-01-04T03:04:01.605Z","repository":{"id":330982712,"uuid":"1124211051","full_name":"yungweng/shared-things","owner":"yungweng","description":"Sync a Things 3 project between multiple macOS users via a self-hosted server","archived":false,"fork":false,"pushed_at":"2025-12-30T14:33:24.000Z","size":138,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T16:27:11.058Z","etag":null,"topics":["cli","collaboration","macos","productivity","self-hosted","sync","things3","todo"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/shared-things-daemon","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yungweng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T15:15:47.000Z","updated_at":"2025-12-30T14:33:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yungweng/shared-things","commit_stats":null,"previous_names":["yungweng/shared-things"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/yungweng/shared-things","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yungweng%2Fshared-things","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yungweng%2Fshared-things/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yungweng%2Fshared-things/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yungweng%2Fshared-things/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yungweng","download_url":"https://codeload.github.com/yungweng/shared-things/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yungweng%2Fshared-things/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28196871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-04T02:00:06.065Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","collaboration","macos","productivity","self-hosted","sync","things3","todo"],"created_at":"2026-01-02T01:52:41.288Z","updated_at":"2026-01-04T03:04:01.599Z","avatar_url":"https://github.com/yungweng.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/shared-things-daemon\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/shared-things-daemon.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yungweng/shared-things/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/shared-things-daemon.svg\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/node/v/shared-things-daemon.svg\" alt=\"node version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# shared-things\n\n**Sync a Things 3 project between multiple macOS users**\n\nStop 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.\n\n\u003c!--\nTODO: Add demo GIF showing sync in action\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.gif\" alt=\"shared-things demo\" width=\"600\"\u003e\n\u003c/p\u003e\n--\u003e\n\n## Quick Start\n\n**Client (each user)**\n```bash\nnpm install -g shared-things-daemon\nshared-things init\n```\nThat's it. Follow the prompts.\n\n## Features\n\n- 🔄 **Real-time sync** - Changes propagate within 30 seconds\n- 🏠 **Self-hosted** - No cloud subscription, host on your own server\n- 👥 **Multi-user** - Each person gets their own API key\n- 🤫 **Background daemon** - Auto-starts on login, runs silently\n- 🛠️ **Interactive CLI** - Easy setup wizard for configuration\n\n## Prerequisites\n\n- **macOS** with [Things 3](https://culturedcode.com/things/) installed\n- **Node.js \u003e= 18**\n- A server running `shared-things-server` (see [Server Setup](#server-setup))\n\n## Usage\n\n### Interactive Mode\n\n```bash\nshared-things init\n```\n```\n? Server URL: https://things.yourdomain.com\n? API Key: ****\n? Project name in Things: Shared Project\n? Things auth token: ****\n```\n\n\u003e **Things auth token:** Required for syncing updates to existing todos. Find it in Things → Settings → General → Things URLs → Enable Things URLs.\n\n### After Setup\n\n```bash\nshared-things install   # Start daemon (auto-runs on login)\nshared-things status    # Check sync status\nshared-things logs -f   # Follow sync logs\n```\n\n### All Commands\n\n| Command | Description |\n|---------|-------------|\n| `init` | Setup wizard |\n| `install` | Install launchd daemon (auto-starts on login) |\n| `uninstall` | Remove launchd daemon |\n| `status` | Show sync status \u0026 last sync time |\n| `sync` | Force immediate sync |\n| `logs [-f]` | Show logs (`-f` to follow) |\n| `reset [--server]` | Reset local state (`--server` clears server too) |\n| `purge` | Remove all local config |\n\n## Server Setup\n\nOne person hosts the server. Everyone else just needs an API key.\n\n```bash\n# Install\nnpm install -g shared-things-server\n\n# Create a user (generates API key)\nshared-things-server create-user\n# → User \"alice\" created. API key: sk_abc123...\n\n# Start server\nshared-things-server start -d --port 3334\n```\n\n### Server Commands\n\n| Command | Description |\n|---------|-------------|\n| `start [-d] [-p port]` | Start server (`-d` for background) |\n| `stop` | Stop background server |\n| `status` | Show server status |\n| `logs [-f]` | Show logs (`-f` to follow) |\n| `create-user` | Create user and generate API key |\n| `list-users` | List all users |\n| `delete-user` | Delete a user |\n| `reset` | Delete all todos (keeps users) |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProduction Deployment\u003c/strong\u003e\u003c/summary\u003e\n\n### systemd Service\n\n```bash\nsudo tee /etc/systemd/system/shared-things.service \u003c\u003c 'EOF'\n[Unit]\nDescription=shared-things sync server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/bin/shared-things-server start --port 3334\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\nsudo systemctl enable --now shared-things\n```\n\n### HTTPS with Caddy\n\n```\nthings.yourdomain.com {\n    reverse_proxy localhost:3334\n}\n```\n\n\u003c/details\u003e\n\n## What Syncs\n\n| Synced | Not Synced |\n|--------|------------|\n| Todo title, notes, due date, tags | Completed todos |\n| Headings | Checklist items |\n| | Areas |\n\n\u003e **Note:** The project must exist in each user's Things app. Only items within that project sync.\n\n## How It Works\n\n```\nThings User A ←→ Daemon A ←→ Server ←→ Daemon B ←→ Things User B\n```\n\nEach 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).\n\n## Development\n\n```bash\ngit clone https://github.com/yungweng/shared-things.git\ncd shared-things\npnpm install\npnpm build\n```\n\n## Contributing\n\nIssues and PRs welcome! See [open issues](https://github.com/yungweng/shared-things/issues).\n\n## Links\n\n- [Repository](https://github.com/yungweng/shared-things)\n- [Issues](https://github.com/yungweng/shared-things/issues)\n- [npm (daemon)](https://www.npmjs.com/package/shared-things-daemon)\n- [npm (server)](https://www.npmjs.com/package/shared-things-server)\n\n## Author\n\nMaintained by [@yungweng](https://github.com/yungweng)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyungweng%2Fshared-things","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyungweng%2Fshared-things","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyungweng%2Fshared-things/lists"}