{"id":23388249,"url":"https://github.com/san-ghun/ywfm","last_synced_at":"2026-04-10T23:51:22.453Z","repository":{"id":266739799,"uuid":"899214175","full_name":"san-ghun/ywfm","owner":"san-ghun","description":"ywfm, \"You're welcome, future me!\", is a CLI reminder program for macOS and Linux. ","archived":false,"fork":false,"pushed_at":"2025-04-01T19:34:58.000Z","size":67,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T19:40:20.516Z","etag":null,"topics":["cli","cmdline","command-line","command-line-tool","commandline","linux","macos","notification","python","python3","reminder","thanks","thankyou"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/san-ghun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-12-05T20:40:08.000Z","updated_at":"2025-04-01T19:35:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"b2b15406-479d-4410-88fe-3c76bcc4af26","html_url":"https://github.com/san-ghun/ywfm","commit_stats":null,"previous_names":["san-ghun/ywfm"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/san-ghun%2Fywfm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/san-ghun%2Fywfm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/san-ghun%2Fywfm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/san-ghun%2Fywfm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/san-ghun","download_url":"https://codeload.github.com/san-ghun/ywfm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247847765,"owners_count":21006127,"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","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","cmdline","command-line","command-line-tool","commandline","linux","macos","notification","python","python3","reminder","thanks","thankyou"],"created_at":"2024-12-22T02:18:21.331Z","updated_at":"2026-04-10T23:51:22.442Z","avatar_url":"https://github.com/san-ghun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ywfm - \"You're welcome, future me!\"\n\n\u003e \"Do something today that your future self will thank you for.\"\n\nA simple Python3-based reminder tool for macOS and Linux that uses native notification systems to alert the user after a specified time. It also supports opening URLs and executing commands when the timer ends.\n\n- [한국어](/docs/readme/kor.md)\n\n## Features\n\n- **Cross-platform**: Works on macOS (using `terminal-notifier`) and Linux (using `notify-send`).\n- **Customizable notifications**: Add a subject, message, URL to open, and a command to execute.\n- **Timer support**: Specify the delay using a human-readable format like `1h10m15s`.\n- **Visual feedback**: Option to run the reminder visually with a progress bar.\n- **Background execution**: Option to run the reminder as a background process with logging.\n- **Named reminders**: Assign names to reminders for easier management.\n- **Reminder management**: List active reminders and cancel them by PID or name.\n- **Dry run mode**: Preview reminder configuration without executing.\n- **JSON output**: Outputs reminder details in JSON format.\n- **Minimum time limit**: Enforces a minimum time of 15 seconds for all reminders.\n- **Default messages**: Provides friendly default messages if none specified.\n- **Logging**: Stores background process logs in `~/.local/state/ywfm/`.\n\n## Requirements\n\n### Python\n\n- Python 3.8 or later\n- `tqdm` package for progress bar visualization\n\n### System Dependencies\n\n- **macOS**:\n  - `terminal-notifier` for notifications\n  - Homebrew (recommended for installing dependencies)\n- **Linux**:\n  - `notify-send` (libnotify-bin) for notifications\n  - `xdg-utils` for opening URLs\n  - Supported package managers: apt, dnf, yum, pacman, zypper\n\n## Installation\n\n### Automated Installation\n\nThe installer script (`install.py`) handles all dependencies and setup:\n\n1. Clone or download the repository\n2. Run the installer:\n\n   ```bash\n   python3 install.py\n   ```\n\n   The installer will:\n\n   - Check for missing system dependencies\n   - Auto-detect your package manager (apt, dnf, pacman, etc.)\n   - Prompt before installing any missing dependencies\n   - Install required Python packages\n   - Set up the executable in your PATH\n\n   Note: You may need:\n\n   - macOS: Homebrew installed (https://brew.sh)\n   - Linux: sudo privileges for package installation\n\n3. The installer will guide you through adding the following to your PATH:\n   ```bash\n   export PATH=\"$HOME/.local/bin:$PATH\"\n   ```\n   Add this to your shell config file (`~/.bashrc`, `~/.zshrc`, etc.) for persistence.\n\n### Manual Installation\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to expand manual installation steps\u003c/summary\u003e\n\n#### Prerequisites Check\n\n1. Check system dependencies:\n\n   - macOS: `which terminal-notifier`\n   - Linux: `which notify-send xdg-open`\n\n2. Check Python packages:\n   ```bash\n   python3 -m pip show tqdm\n   ```\n\n#### System Dependencies\n\n1. macOS:\n\n   ```bash\n   brew install terminal-notifier\n   ```\n\n2. Linux (choose your distribution):\n   ```bash\n   # Debian/Ubuntu\n   sudo apt install -y libnotify-bin xdg-utils\n\n   # Fedora/RHEL\n   sudo dnf install -y libnotify xdg-utils\n\n   # Arch Linux\n   sudo pacman -S libnotify xdg-utils\n\n   # openSUSE\n   sudo zypper install -y libnotify-tools xdg-utils\n   ```\n\n#### Python Dependencies\n\n1. Install required package:\n   ```bash\n   python3 -m pip install --user tqdm\n   ```\n\n#### Script Installation\n\n1. Create installation directory:\n\n   ```bash\n   mkdir -p ~/.local/bin\n   ```\n\n2. Make script executable and install:\n\n   ```bash\n   chmod +x main.py\n   cp main.py ~/.local/bin/ywfm\n   ```\n\n3. Add to PATH (if not already added):\n   ```bash\n   echo 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc  # or ~/.zshrc\n   source ~/.bashrc  # or ~/.zshrc\n   ```\n   \u003c/details\u003e\n\n## Usage\n\n```bash\nywfm [-h] [-l | --cancel PID_OR_NAME] [-n NAME] [-s SUBJECT] [-m MESSAGE] -t TIMER [-o OPEN_URL] [-c COMMAND] [-p] [-b] [--dry-run]\n```\n\n### Options\n\n| Option                 | Description                                | Default      |\n| ---------------------- | ------------------------------------------ | ------------ |\n| `-l` `--list`          | List all active background reminders       | -            |\n| `--cancel PID_OR_NAME` | Cancel a reminder by PID or name           | -            |\n| `-n` `--name`          | Name for the reminder (for easier cancel)  | None         |\n| `-s` `--subject`       | Subject for the reminder notification      | \"ywfm\"       |\n| `-m` `--message`       | Message for the notification               | Random\\*     |\n| `-t` `--timer`         | Timer duration (e.g., `1h10m15s`, `10s`)   | **Required** |\n| `-o` `--open-url`      | URL to open when notification triggers     | None         |\n| `-c` `--command`       | Command to execute after timer ends        | None         |\n| `-p` `--show-progress` | Show progress bar                          | False        |\n| `-b` `--background`    | Run as background process                  | False        |\n| `--dry-run`            | Preview configuration without executing    | False        |\n\n\\* Default messages alternate between \"Well done!\" and \"You're welcome!\"\n\n### Examples\n\n1. **Simple Reminder**:\n\n   ```bash\n   ywfm -t 30m -s \"Time to Work\" -m \"Start your project\"\n   ```\n\n2. **Open URL on Timer**:\n\n   ```bash\n   ywfm -t 10s -s \"Check GitHub\" -m \"Review PRs\" -o \"https://github.com\"\n   ```\n\n3. **Execute Command**:\n\n   ```bash\n   ywfm -t 1m -s \"Build\" -c 'make clean \u0026\u0026 make'\n   ```\n\n4. **Named Background Reminder**:\n\n   ```bash\n   ywfm -t 2h -s \"Long Task\" -n mytask -b\n   ```\n\n   Output:\n\n   ```json\n   {\n     \"pid\": 12345,\n     \"params\": {\n       \"name\": \"mytask\",\n       \"subject\": \"Long Task\",\n       \"message\": \"Well done!\",\n       \"duration\": \"2h\",\n       \"url\": null,\n       \"command\": null,\n       \"show-progress\": false,\n       \"background\": true\n     },\n     \"info\": {\n       \"created_at\": \"2024-03-21_14:30:00\",\n       \"trigger_at\": \"2024-03-21_16:30:00\",\n       \"seconds\": 7200\n     },\n     \"extra\": {\n       \"os_name\": \"Darwin\",\n       \"machine\": \"x86_64\",\n       \"node\": \"Sanghun.local\",\n       \"platform\": \"macOS-14.7-x86_64-i386-64bit\",\n       \"description\": \"Logs stored in '~/.local/state/ywfm'\"\n     }\n   }\n   ```\n\n5. **Progress Bar**:\n\n   ```bash\n   ywfm -t 10m -s \"Break\" -m \"Coffee time!\" -p\n   ```\n\n6. **Preview with Dry Run**:\n\n   ```bash\n   ywfm -t 1h30m -s \"Meeting\" --dry-run\n   ```\n\n## Background Process Management\n\nWhen running in background mode (`-b`):\n\n- Process ID (PID) is output in JSON format\n- Logs are stored in `~/.local/state/ywfm/`:\n  - `output_[timestamp].log`: Standard output\n  - `error_[timestamp].log`: Error messages\n  - `[timestamp].json`: Reminder configuration\n  - `ywfm.pid`: Current process PID\n\n### List Active Reminders\n\n```bash\nywfm --list\n```\n\nOutput:\n```\nPID      Name         Subject          Trigger At           Duration\n--------------------------------------------------------------------\n12345    mytask       Long Task        2024-03-21_16:30:00  2h\n12346    -            Break            2024-03-21_14:45:00  30m\n```\n\n### Cancel a Reminder\n\nBy PID:\n```bash\nywfm --cancel 12345\n```\n\nBy name:\n```bash\nywfm --cancel mytask\n```\n\nLegacy method (still works):\n```bash\nkill $(cat ~/.local/state/ywfm/ywfm.pid)\n```\n\n## Uninstallation\n\n1. Remove the executable:\n\n   ```bash\n   rm ~/.local/bin/ywfm\n   ```\n\n2. Optional: Remove log directory:\n\n   ```bash\n   rm -rf ~/.local/state/ywfm\n   ```\n\n3. Optional: Remove dependencies:\n   - macOS: `brew uninstall terminal-notifier`\n   - Linux: `sudo apt remove libnotify-bin xdg-utils`\n\n## Contributing\n\nFeel free to fork the repository and submit pull requests for improvements.\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Author\n\nSanghun Park\n\n---\n\n\u003e Thank you, past me.\n\u003e\n\u003e _Good job, future me._\n\u003e\n\u003e Well done, past me.\n\u003e\n\u003e _You're welcome, future me._\n\u003e\n\u003e Thanks a lot.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsan-ghun%2Fywfm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsan-ghun%2Fywfm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsan-ghun%2Fywfm/lists"}