claude-connect/QUICKSTART.md

Quickstart Guide

Get up and running in under 2 minutes.

---

1. Test Auto-Detection (Optional)

See what notification settings will be auto-detected:

./test-detection.sh

Example output:

✓ Detection successful!

Would configure:
  notification_channel: telegram
  notification_target: 123456789

---

2. Verify System

Check that all requirements are met:

./verify-setup.sh

Should show:

• ✓ macOS version
• ✓ Claude CLI installed
• ✓ Keychain credentials
• ✓ Bot running
• ✓ Auto-detected: telegram → 123456789

---

3. Install

One command to set everything up:

./install.sh

What it does:

1. Runs verification
2. Auto-detects your notification settings
3. Interactively configures notification types (start/success/failure)
4. Creates claude-oauth-refresh-config.json with your preferences
5. Tests token refresh immediately
6. Sets up launchd (runs every 2 hours)
7. Starts the service

Expected output:

[1/6] Running verification...
[2/6] Setting up config...
  ✓ Auto-detected: telegram → 123456789
  ✓ Created config with auto-detected values
[3/6] Testing token refresh...
  ✓ Refresh successful
[4/6] Creating launchd service...
  ✓ Created plist
[5/6] Installing launchd service...
  ✓ Loaded service
[6/6] Verifying installation...
  ✓ Service is running

✓ Installation complete!

---

4. Monitor (Optional)

Watch the logs to see refreshes happen:

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

You should see:

[2026-01-23 10:05:30] Starting token refresh check...
[2026-01-23 10:05:31] Token expires in 720 minutes
[2026-01-23 10:05:31] Token still valid, no refresh needed (buffer: 30 min)

---

Done! 🎉

Your Claude CLI will now:

• Automatically refresh tokens before they expire
• Notify you if anything goes wrong
• Log all activity to ~/bot/logs/

---

Customization

Change Notification Settings

Edit claude-oauth-refresh-config.json:

nano claude-oauth-refresh-config.json

Change notification types, channel, or target as needed. Changes apply automatically!

Test Manual Refresh

Run the refresh script directly:

./refresh-token.sh

Check Service Status

launchctl list | grep claude-oauth-refresher

---

Troubleshooting

Problem: Auto-detection didn't find my channel

Solution: Edit claude-oauth-refresh-config.json manually and set your preferred channel. See SKILL.md section "Finding Your Target ID" for examples.

---

Problem: Service not running after install

Solution:

# Load manually
launchctl load ~/Library/LaunchAgents/com.bot.claude-oauth-refresher.plist

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

---

Problem: Want to change notification settings

Solution: Just edit the config - no reinstall needed:

nano claude-oauth-refresh-config.json
# Change notifications, channel, or target
# Changes apply automatically on next refresh

Or ask Bot:

"disable Claude refresh start notifications"
"enable all Claude refresh notifications"

---

Uninstall

./uninstall.sh

Removes the service but keeps your scripts and config.

---

Need more details? See SKILL.md for complete documentation.