hanzoskill/claude-oauth-refresher

Fork 0

mirror of https://github.com/hanzoskill/claude-oauth-refresher.git synced 2026-10-30 21:04:23 +00:00

Files

T

zeekay 52aa9dc920 Initial import of claude-oauth-refresher skill (author: tunaissacoding)

2026-02-11 03:16:51 -08:00

8.1 KiB

Raw Permalink Blame History

Upgrade Guide

What's New

This update brings significant improvements to notification handling and user experience:

🎉 Major Features

Three Notification Types - Fine-grained control:
- 🔄 Start: "Refreshing Claude token..."
- ✅ Success: "Claude token refreshed!"
- ❌ Failure: Detailed error with troubleshooting
Interactive Installation - Prompts during setup:
- Configure which notification types you want
- Smart recommendations
- Easy to change later
Bot Control - Voice/text commands to manage settings:
- "disable Claude refresh start notifications"
- "show Claude refresh notification settings"
- "enable all Claude refresh notifications"
Detailed Failure Messages - Context-specific troubleshooting:
- Network errors → connection troubleshooting
- Invalid token → re-authentication steps
- Keychain issues → permission fixes
One-Time Installer - Clearer workflow:
- Install ONCE to set up recurring job
- Config changes apply automatically
- Only re-run to reinstall/fix
Config File Renamed:
- Old: config.json
- New: claude-oauth-refresh-config.json
- More descriptive and avoids conflicts

Upgrading from Previous Version

Automatic Migration (Recommended)

Simply re-run the installer:

cd ~/bot/skills/claude-oauth-refresher
./install.sh

The installer will:

✅ Detect your old config.json
✅ Migrate to new claude-oauth-refresh-config.json format
✅ Add new notification type structure
✅ Preserve your existing settings
✅ Prompt for notification preferences
✅ Update the launchd job
✅ Clean up old config file

Manual Migration

If you prefer manual control:

Backup your current config:
```
cp config.json config.json.backup
```

Create new config with your settings:

cat > claude-oauth-refresh-config.json << 'EOF'
{
  "refresh_buffer_minutes": 30,
  "log_file": "~/bot/logs/claude-oauth-refresh.log",
  "notifications": {
    "on_start": false,
    "on_success": false,
    "on_failure": true
  },
  "notification_channel": "telegram",
  "notification_target": "YOUR_CHAT_ID_HERE"
}
EOF

Copy your old notification_target:

# Extract from old config
OLD_TARGET=$(jq -r '.notification_target' config.json)

# Update new config
jq --arg target "$OLD_TARGET" '.notification_target = $target' \
  claude-oauth-refresh-config.json > tmp.json && \
  mv tmp.json claude-oauth-refresh-config.json

Remove old config:
```
rm config.json config.json.backup
```
Test the new config:
```
./refresh-token.sh
```

What Changed

Config Structure

Before (config.json):

{
  "refresh_buffer_minutes": 30,
  "log_file": "~/bot/logs/claude-oauth-refresh.log",
  "notify_on_success": false,
  "notify_on_failure": true,
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

After (claude-oauth-refresh-config.json):

{
  "refresh_buffer_minutes": 30,
  "log_file": "~/bot/logs/claude-oauth-refresh.log",
  "notifications": {
    "on_start": true,
    "on_success": true,
    "on_failure": true
  },
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

Script Updates

refresh-token.sh:

✅ Reads new config filename
✅ Supports three notification types
✅ Enhanced error messages with troubleshooting
✅ Detailed failure notifications
✅ Better HTTP error handling
✅ Network timeout detection

install.sh:

✅ Interactive notification prompts
✅ Migrates old config automatically
✅ Shows notification preferences summary
✅ Explains one-time installation model
✅ Better user guidance

verify-setup.sh:

✅ Checks for both old and new config filenames
✅ Suggests migration if old config found

uninstall.sh:

✅ Removes both old and new config files

Breaking Changes

Config File Location

The config file is now named claude-oauth-refresh-config.json instead of config.json.

Impact: Minimal - installer handles migration automatically.

Action Required:

If you run installer: None (automatic)
If you skip installer: Rename manually and update structure

Notification Fields

The notify_on_success and notify_on_failure fields are replaced with:

"notifications": {
  "on_start": true,
  "on_success": true,
  "on_failure": true
}

Impact: Old configs won't work with new scripts.

Action Required:

Run installer for automatic migration
Or manually update config structure

New Features You'll Love

1. Disable Noisy Notifications

After verifying the setup works:

# Option 1: Ask Bot
"disable Claude refresh start notifications"
"disable Claude refresh success notifications"

# Option 2: Edit config
nano claude-oauth-refresh-config.json
# Set on_start and on_success to false

Recommended: Keep only on_failure: true for production.

2. Detailed Troubleshooting

Failure notifications now include:

Specific error message
Detailed context
Targeted troubleshooting steps
Log file location
Help resources

Example:

❌ Claude token refresh failed

Error: Network timeout connecting to auth.anthropic.com
Details: Connection timed out after 30s

Troubleshooting:
- Check your internet connection
- Verify you can reach auth.anthropic.com
- Try running manually: ~/bot/skills/claude-oauth-refresher/refresh-token.sh

Need help? Message Bot or check logs:
~/bot/logs/claude-oauth-refresh.log

3. Config Changes Apply Automatically

No more reinstalling! Just edit the config file and changes apply on the next refresh.

# Edit anytime
nano claude-oauth-refresh-config.json

# Test immediately (optional)
./refresh-token.sh

# Or wait for next scheduled refresh (every 2 hours)

FAQ

Q: Do I need to uninstall first?

A: No! Just run ./install.sh and it will handle everything.

Q: Will I lose my notification settings?

A: No. The installer migrates your existing notification_target and notification_channel.

Q: What if I already have claude-oauth-refresh-config.json?

A: The installer will ask if you want to reconfigure or keep your existing settings.

Q: Can I disable all notifications?

A: Yes, set all three notification types to false in the config. But we recommend keeping on_failure: true so you know about issues.

Q: Do I need to restart anything after changing config?

A: No! The refresh script reads the config file each time it runs. Changes apply automatically.

Q: I want the old behavior (only notify on failure)

A: Edit your config:

"notifications": {
  "on_start": false,
  "on_success": false,
  "on_failure": true
}

Rollback (If Needed)

If you encounter issues and need to roll back:

Uninstall current version:
```
./uninstall.sh
```

Restore old config:

mv claude-oauth-refresh-config.json.backup config.json
# (if you made a backup)

Reinstall old version:

git checkout <previous-commit>
./install.sh

But first: Please report issues so we can fix them!

Support

Issues? Check:

Run ./verify-setup.sh
Check logs: tail -20 ~/bot/logs/claude-oauth-refresh.log
Test manually: ./refresh-token.sh
Check config: cat claude-oauth-refresh-config.json | jq

Still stuck? Open an issue with:

Output of ./verify-setup.sh
Relevant log excerpts
Config file (redact notification_target)

Summary

✅ Run installer to upgrade - handles everything automatically ✅ Config migrated - preserves your settings ✅ New notification types - finer control ✅ Better error messages - easier troubleshooting ✅ Bot integration - voice/text control ✅ No breaking workflow - still runs every 2 hours

Recommended next steps:

Run ./install.sh
Choose notification preferences
Disable start/success notifications after verifying it works
Enjoy hands-free token management!

8.1 KiB Raw Permalink Blame History