claude-oauth-refresher

What This Skill Does

The claude-oauth-refresher is a specialized utility designed for developers and power users who rely on the Claude Code CLI. Because OAuth tokens for CLI tools often have relatively short expiry windows, users frequently face authentication interruptions during long-running tasks or after computer sleep cycles. This skill automates the token refresh lifecycle by monitoring your active session and proactively re-authenticating before your token expires. It operates silently in the background via macOS launchd, ensuring you stay authenticated 24/7 without manual intervention. Beyond simple refreshing, the tool provides robust logging and an optional notification system that keeps you informed of your authentication status, alerting you immediately if a refresh attempt fails so you can intervene before your workflow is blocked.

Installation

To install, ensure you have the OpenClaw agent running and your environment configured. Navigate to your local Clawd directory and execute the following command: cd ~/clawd/skills/claude-oauth-refresher && ./install.sh. The installer is an interactive script that verifies your macOS Keychain access, checks your existing Claude Code CLI setup, and guides you through configuring your notification preferences. The process is one-time only; once installed, it registers a persistent background process that automatically triggers every 2 hours to validate and refresh your credentials as needed.

Use Cases

This skill is essential for users who frequently work within the terminal or run long-duration AI-assisted coding projects. It is perfect for developers working on distributed teams where staying logged in is critical for CI/CD pipeline automation or overnight script execution. It effectively eliminates the "unauthorized" or "token expired" errors that plague CLI users who depend on the Claude ecosystem for complex software engineering tasks.

Example Prompts

1. "disable Claude refresh start notifications"
2. "enable all Claude refresh notifications"
3. "turn on Claude token refresh success messages"

Tips & Limitations

• Limitation: This skill is exclusive to macOS environments due to its reliance on the macOS Keychain for secure token storage.
• Tip: Keep all notifications enabled for the first 24 hours of use to ensure that the background process is successfully communicating with your authentication provider.
• Tip: If you suspect issues, run the included ./verify-setup.sh script to check permissions and token validity before troubleshooting your network or account status.