claude-oauth-refresher

name	claude-oauth-refresher
description	Keep your Claude access token fresh 24/7. Automatically refreshes OAuth tokens before expiry so you never see authentication failures.

claude-oauth-refresher

Automatic OAuth token refresh for Claude Code CLI on macOS

Keep your Claude account logged in 24/7 by automatically refreshing OAuth tokens before they expire.

---

⚠️ Requirements

This skill is macOS-only and requires:

1. macOS (uses Keychain for secure credential storage)
2. Claude Code CLI already installed (claude command available)
3. Already logged into your Claude account (run claude then login - stores tokens in Keychain)
4. Bot installed and running

Not sure if you're set up? Run the verification script:

./verify-setup.sh

---

What It Does

• Monitors your Claude CLI token expiration
• Refreshes tokens automatically before they expire (default: 30 min buffer)
• Notifies you with three notification types:
  • 🔄 Start: "Refreshing Claude token..."
  • ✅ Success: "Claude token refreshed!"
  • ❌ Failure: Detailed error with troubleshooting steps
• Logs all refresh attempts for debugging

---

Installation

Quick Setup (Recommended)

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

This installer runs ONCE and sets up automatic token refresh that runs every 2 hours.

The installer will:

1. Verify your system meets requirements
2. Interactively configure notification preferences
3. Auto-detect your notification target (Telegram, Slack, etc.)
4. Set up launchd for automatic refresh
5. Test the refresh immediately

After installation:

• Config changes apply automatically (refresh script reads config each run)
• Edit claude-oauth-refresh-config.json to change settings
• Ask Bot to modify settings for you
• Only re-run installer if you need to reinstall or fix the job

Interactive Notification Setup

During installation, you'll be prompted:

Configure Notifications:
💡 Recommendation: Keep all enabled for the first run to verify it works.
   You can disable them later by:
   1. Editing ~/bot/claude-oauth-refresh-config.json
   2. Asking Bot: "disable Claude refresh notifications"

Enable "🔄 Refreshing token..." notification? [Y/n]: 
Enable "✅ Token refreshed!" notification? [Y/n]: 
Enable "❌ Refresh failed" notification? [Y/n]: 

Recommendation: Keep all enabled initially to verify everything works, then disable start/success notifications once you're confident.

---

Managing Notifications with Bot

You can ask Bot to change notification settings for you! No need to edit JSON manually.

Examples

Disable specific notification types:

"disable Claude refresh start notifications"
"disable Claude refresh success notifications"
"turn off Claude token refresh start messages"

Enable notification types:

"enable Claude refresh start notifications"
"enable all Claude refresh notifications"
"turn on Claude token refresh success messages"

Check current settings:

"show Claude refresh notification settings"
"what are my Claude token refresh notification settings?"

Disable all notifications:

"disable all Claude refresh notifications"
"turn off all Claude token notifications"

Reset to defaults:

"reset Claude refresh notifications to defaults"

How It Works

Bot will:

1. Read your ~/bot/claude-oauth-refresh-config.json
2. Update the appropriate notification flags
3. Save the file
4. Confirm the changes

Changes apply immediately on the next refresh (no need to restart anything).

---

Auto-Detection (Smart Defaults)

The install script automatically detects your notification settings!

It reads ~/.bot/bot.json to find:

• Which messaging channels you have enabled
• Your chat ID, phone number, or user ID
• Automatically populates claude-oauth-refresh-config.json with these values

Example: If you have Telegram enabled with chat ID 123456789, the installer creates:

{
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

To override: Simply edit claude-oauth-refresh-config.json after installation to use a different channel or target.

If auto-detection fails: The installer will prompt you to configure manually (see "Finding Your Target ID" below).

Test detection before installing:

./test-detection.sh
# Shows what would be auto-detected without modifying anything

---

Finding Your Target ID

To receive notifications, you need to configure your notification_target in claude-oauth-refresh-config.json. Here's how to find it for each channel:

Telegram

Format: Numeric chat ID (e.g., 123456789)

How to find:

# Option 1: Use Bot CLI
bot message telegram account list

# Option 2: Message @userinfobot on Telegram
# Send any message, it will reply with your ID

# Option 3: Check recent messages
bot message telegram message search --limit 1 --from-me true

Example config:

{
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

Slack

Format:

• Direct messages: user:U01234ABCD
• Channels: channel:C01234ABCD

How to find:

# List channels
bot message slack channel list

# Find user ID
bot message slack user list | grep "[e-mail]"

# Or click on your profile in Slack → More → Copy member ID

Example config:

{
  "notification_channel": "slack",
  "notification_target": "user:U01234ABCD"
}

Discord

Format:

• Direct messages: user:123456789012345678
• Channels: channel:123456789012345678

How to find:

# Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
# Then right-click your username → Copy ID

# Or list channels
bot message discord channel list

Example config:

{
  "notification_channel": "discord",
  "notification_target": "user:123456789012345678"
}

WhatsApp

Format: E.164 phone number (e.g., [phone])

How to find:

• Use your full phone number with country code
• Format: +[country code][number] (no spaces, dashes, or parentheses)

Examples:

• US: [phone]
• UK: [phone]
• Australia: [phone]

Example config:

{
  "notification_channel": "whatsapp",
  "notification_target": "[phone]"
}

iMessage

Format (preferred): chat_id:123

How to find:

# List recent chats to find your chat_id
bot message imessage thread list --limit 10

# Find the chat with yourself or your preferred device

Alternative formats:

• Phone: [phone] (E.164 format)
• Email: [e-mail]

Example config:

{
  "notification_channel": "imessage",
  "notification_target": "chat_id:123"
}

Signal

Format: E.164 phone number (e.g., [phone])

How to find:

• Use your Signal-registered phone number
• Format: +[country code][number] (no spaces, dashes, or parentheses)

Example config:

{
  "notification_channel": "signal",
  "notification_target": "[phone]"
}

---

Configuration

File: 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": "YOUR_CHAT_ID"
}

Options

Option	Type	Default	Description
refresh_buffer_minutes	number	30	Refresh tokens this many minutes before expiry
log_file	string	~/bot/logs/claude-oauth-refresh.log	Where to write logs
notifications.on_start	boolean	true	Send "🔄 Refreshing token..." notification
notifications.on_success	boolean	true	Send "✅ Token refreshed!" notification
notifications.on_failure	boolean	true	Send "❌ Refresh failed" notification with details
notification_channel	string	telegram	Channel to use (see above for options)
notification_target	string	YOUR_CHAT_ID	Target ID (see "Finding Your Target ID")

Notification Types Explained

🔄 Start (on_start)

• Sent when refresh process begins
• Useful for debugging or knowing when refresh runs
• Recommendation: Disable once you verify it works (can be noisy)

✅ Success (on_success)

• Sent when token successfully refreshed
• Includes validity duration (e.g., "valid for 24h")
• Recommendation: Disable once you trust the setup (can be noisy)

❌ Failure (on_failure)

• Sent when refresh fails with detailed error info
• Includes troubleshooting steps based on error type
• Recommendation: Keep enabled! You want to know about failures.

Example Configurations

Minimal (failures only):

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

Verbose (all notifications):

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

Silent (no notifications):

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

---

Detailed Failure Messages

When a refresh fails, you'll receive a detailed notification with:

1. Error message - What went wrong
2. Details - Additional context (HTTP codes, error responses, etc.)
3. Troubleshooting - Specific steps based on the error type
4. Help - Where to find logs and get support

Example Failure Notification

❌ 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

Common Errors and Solutions

Network/Timeout Errors

Troubleshooting:
- Check your internet connection
- Verify you can reach auth.anthropic.com
- Try running manually: ./refresh-token.sh

Invalid Refresh Token

Troubleshooting:
- Your refresh token may have expired
- Re-authenticate: claude auth logout && claude auth
- Verify Keychain access: security find-generic-password -s 'claude-cli-auth' -a 'default'

Keychain Access Denied

Troubleshooting:
- Check Keychain permissions
- Re-run authentication: claude auth
- Verify setup: ./verify-setup.sh

Missing Auth Profile

Troubleshooting:
- Run: claude auth
- Verify file exists: ~/.config/claude/auth-profiles.json
- Check file permissions: chmod 600 ~/.config/claude/auth-profiles.json

---

Usage

Check Status

# View recent logs
tail -f ~/bot/logs/claude-oauth-refresh.log

# Check launchd status
launchctl list | grep claude-oauth-refresher

# Manual refresh (for testing)
cd ~/bot/skills/claude-oauth-refresher
./refresh-token.sh

Modify Settings

Option 1: Ask Bot (easiest)

"disable Claude refresh start notifications"
"show Claude refresh notification settings"

Option 2: Edit config file

nano ~/bot/skills/claude-oauth-refresher/claude-oauth-refresh-config.json

Changes apply automatically on next refresh (every 2 hours, or when you run manually).

No need to restart anything! The refresh script reads the config file each time it runs.

---

Troubleshooting

Problem: verify-setup.sh says Claude CLI not found

Solution:

# Install Claude CLI
brew install claude

# Or download from https://github.com/anthropics/claude-cli

---

Problem: verify-setup.sh says no refresh token found

Solution:

# Authenticate with Claude
claude auth

# Follow the prompts to log in

---

Problem: Notifications not arriving

Solution:

1. Check your notification_target format matches the examples above
2. Test manually:

   bot message [channel] send --target "[your_target]" --message "Test"
   

3. Check Bot is running: bot gateway status
4. Verify notification settings:

   cat ~/bot/skills/claude-oauth-refresher/claude-oauth-refresh-config.json | jq .notifications
   

---

Problem: Token refresh fails with "invalid_grant"

Solution:

# Re-authenticate from scratch
claude auth logout
claude auth

# Test refresh again
cd ~/bot/skills/claude-oauth-refresher
./refresh-token.sh

---

Problem: "Config file not found" after upgrade

Solution: The config file was renamed from config.json to claude-oauth-refresh-config.json.

# If you have an old config.json, run the installer to migrate:
cd ~/bot/skills/claude-oauth-refresher
./install.sh
# Choose to keep existing config when prompted

---

Problem: Want to reinstall or fix the job

Solution:

# Re-run the installer (safe to run multiple times)
cd ~/bot/skills/claude-oauth-refresher
./install.sh

The installer will:

• Detect existing config and ask if you want to keep it
• Update the launchd job
• Test the refresh

---

Uninstall

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

This will:

• Stop and unload the launchd service
• Remove the plist file
• Optionally delete logs and config

---

How It Works

1. Installer (install.sh) - Run ONCE to set up:

   • Auto-detects notification target
   • Interactively configures notification types
   • Creates launchd job
   • Tests refresh immediately

2. Launchd - Runs refresh-token.sh every 2 hours automatically

3. Refresh Script (refresh-token.sh) - Each run:

   • Reads config file (changes apply automatically!)
   • Checks token expiration from ~/.config/claude/auth-profiles.json
   • If token expires within buffer window (default 30 min):
     • Sends start notification (if enabled)
     • Retrieves refresh token from Keychain
     • Calls OAuth endpoint to get new tokens
     • Updates auth profile and Keychain
     • Sends success notification (if enabled)
   • If refresh fails:
     • Sends detailed failure notification with troubleshooting
   • All activity logged to ~/bot/logs/claude-oauth-refresh.log

4. Config Changes - Applied automatically:

   • Edit claude-oauth-refresh-config.json anytime
   • Ask Bot to edit for you
   • Changes take effect on next refresh
   • No restart needed!

---

Security

• Tokens are never written to logs or config files
• Refresh tokens stored securely in macOS Keychain
• Access tokens cached in ~/.config/claude/auth-profiles.json (permissions: 600)
• All HTTP requests use Claude's official OAuth endpoints
• Config file is world-readable (contains no secrets)

---

Support

Logs: ~/bot/logs/claude-oauth-refresh.log

Issues:

1. Run ./verify-setup.sh to diagnose
2. Check logs for detailed error messages
3. Test manual refresh: ./refresh-token.sh
4. Check notification settings: cat claude-oauth-refresh-config.json | jq .notifications

Need help? Open an issue with:

• Output of ./verify-setup.sh
• Last 20 lines of logs: tail -20 ~/bot/logs/claude-oauth-refresh.log
• macOS version: sw_vers
• Config (redacted): cat claude-oauth-refresh-config.json | jq 'del(.notification_target)'