keychain-backup-hook

keychain-backup-hook

Prevents Claude Code from deleting your macOS Keychain OAuth credential when CLAUDE_CODE_OAUTH_TOKEN is set as an environment variable.

Problem

When CLAUDE_CODE_OAUTH_TOKEN is set, Claude Code silently deletes the macOS Keychain credential entry on exit. This breaks all other Claude Code sessions that rely on the Keychain credential.

See: anthropics/claude-code#37512

How It Works

• SessionStart hook (keychain-backup.sh): Detects CLAUDE_CODE_OAUTH_TOKEN, reads the existing Keychain credential, and saves it to a secure temp file (chmod 600, user-scoped directory).
• SessionEnd hook (keychain-restore.sh): Checks if the Keychain credential was deleted during the session and restores it from the backup.

The hooks are no-ops when CLAUDE_CODE_OAUTH_TOKEN is not set.

Install

./install.sh

This adds SessionStart and SessionEnd hooks to ~/.claude/settings.json.

Configuration

Variable	Default	Description
CLAUDE_KEYCHAIN_SERVICE	claude.ai	Keychain service name for the credential

Manual Install

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "/path/to/keychain-backup.sh"
      }
    ],
    "SessionEnd": [
      {
        "type": "command",
        "command": "/path/to/keychain-restore.sh"
      }
    ]
  }
}