https://github.com/yungweng/github-things-sync
Sync GitHub PRs and Issues to Things 3 on macOS — automatic task creation and completion tracking
https://github.com/yungweng/github-things-sync
automation cli developer-tools github macos nodejs productivity task-management things3 typescript
Last synced: 6 months ago
JSON representation
Sync GitHub PRs and Issues to Things 3 on macOS — automatic task creation and completion tracking
- Host: GitHub
- URL: https://github.com/yungweng/github-things-sync
- Owner: yungweng
- License: mit
- Created: 2025-12-28T13:20:58.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-02T00:14:27.000Z (6 months ago)
- Last Synced: 2026-01-02T01:14:12.871Z (6 months ago)
- Topics: automation, cli, developer-tools, github, macos, nodejs, productivity, task-management, things3, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/github-things-sync
- Size: 998 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# github-things-sync
**Automatically sync your GitHub PRs and Issues to Things 3 on macOS.**
Stop manually creating todos for your GitHub work. github-things-sync watches your assigned issues, PR reviews, and created items—automatically creating and completing tasks in Things 3.
## Quick Start
```bash
npm install -g github-things-sync
github-things-sync init
```
*Follow the prompts, then:*
```bash
github-things-sync start
```
## Features
- 🔄 **Auto-sync** — PRs and issues appear in Things automatically
- ✅ **Completion tracking** — Close an issue, task completes in Things
- 📋 **Smart filtering** — Choose what to sync (reviews, created, assigned)
- 🎯 **Repository scope** — Select specific repos or orgs to sync
- 🚀 **Background daemon** — Runs silently, syncs every 5 minutes
- 🍎 **macOS native** — Uses LaunchAgent for autostart
## What Gets Synced
| GitHub | → | Things |
|--------|---|--------|
| PR review requested | → | Todo in "GitHub" project |
| Issue assigned to you | → | Todo with issue link |
| PR you created | → | Todo with PR link |
| Issue you created | → | Todo with issue link |
| Closed/merged item | → | Task marked complete |
## Prerequisites
- macOS (Things 3 is macOS/iOS only)
- [Things 3](https://culturedcode.com/things/) installed
- Node.js 20+
- [GitHub Personal Access Token](https://github.com/settings/tokens) (classic, `repo` scope)
## Installation
### Via npm (recommended)
```bash
npm install -g github-things-sync
github-things-sync init
```
### Via npx (no install)
```bash
npx github-things-sync init
```
Manual installation from source
```bash
git clone https://github.com/yungweng/github-things-sync.git
cd github-things-sync
pnpm install && pnpm build
pnpm link --global
```
## Commands
| Command | Description |
|---------|-------------|
| `init` | Interactive setup wizard |
| `start` | Start background sync daemon |
| `stop` | Stop the daemon |
| `status` | Show daemon status and task mappings |
| `sync` | Run a single sync (no daemon) |
| `config` | View or update settings |
| `config --verify` | Verify your tokens work |
## How It Works
```
┌─────────────┐ Poll ┌──────────────┐ AppleScript ┌──────────┐
│ GitHub │ ◄──────────── │ Daemon │ ─────────────────► │ Things 3 │
│ API │ │ (background) │ URL Scheme │ App │
└─────────────┘ └──────────────┘ └──────────┘
│
▼
~/.github-things-sync/
├── config.json
├── state.json
└── daemon.log
```
The daemon polls GitHub every 5 minutes (configurable) for:
- PRs where you're requested as reviewer
- PRs you created
- Issues assigned to you
- Issues you created
When items are found, it creates tasks in Things 3 via AppleScript. When items close/merge on GitHub, the corresponding tasks are completed via URL Scheme.
## Configuration
After running `init`, your config is stored at `~/.github-things-sync/config.json`.
Update settings with:
```bash
github-things-sync config --interval=600 # Poll every 10 minutes
github-things-sync config --project="Work" # Use different Things project
github-things-sync config --sync-types=pr-reviews,issues-assigned
github-things-sync config --repos=prompt # Select specific repos to sync
github-things-sync config --repos=all # Reset to sync all repos
```
## Development
```bash
git clone https://github.com/yungweng/github-things-sync.git
cd github-things-sync
pnpm install
pnpm dev sync -v # Run sync in dev mode
```
## Contributing
Found a bug or have a feature request? [Open an issue](https://github.com/yungweng/github-things-sync/issues).
Pull requests are welcome!
## License
MIT © [yungweng](https://github.com/yungweng)