Claude Profiles

A powerful CLI tool to manage multiple Claude configuration profiles using GitHub Gists as secure cloud storage. This tool enables you to store, restore, and synchronize Claude configurations across machines, supporting both macOS and Linux platforms with automatic credential format conversion.

Perfect for developers working with:

• Cloud Development Environments: GitPod, GitHub Codespaces, and other cloud IDEs
• Multiple Devices: Seamlessly sync profiles between your macOS laptop, Linux desktop, and cloud workspaces
• Team Environments: Share configurations across team development environments
• Ephemeral Environments: Quickly restore your Claude setup in temporary containers or VMs

Features

Core Functionality

• Profile Management: Store, restore, and delete multiple Claude configuration profiles
• Cloud Storage: Uses GitHub Gists (secret) for secure profile storage
• Cross-Platform Support: Works on macOS and Linux with automatic credential format conversion
• macOS Keychain Integration: Fully supports macOS Keychain credentials storage and retrieval
• Watch Mode: Automatically saves configuration changes to a profile with intelligent debouncing
• Profile Verification: Validates profile integrity before restoration
• No Dependencies: Uses dynamic module loading (use-m) - no package.json required
• Comprehensive Logging: Optional file logging and verbose mode for debugging

What Gets Backed Up

• ~/.claude/ directory - entire directory with all subdirectories and files:
  • IDE lock files (ide/*.lock)
  • Plugin configurations (plugins/)
  • Project history and conversations (projects/)
  • Todo items (todos/)
  • Shell snapshots (shell-snapshots/)
  • Settings and statistics (settings.json, statsig/)
  • All other Claude-related data
• ~/.claude.json (main configuration file)
• ~/.claude.json.backup (configuration backup)
• macOS Keychain credentials (exported to archive as .macos.credentials.json)
• Linux credentials file (~/.claude/.credentials.json)

Restore Behavior

Important: When restoring a profile:

• Files are overwritten: Existing files with the same name will be replaced
• New files are added: Files from the backup are added to existing directories
• Existing files are preserved: Files not in the backup remain untouched
• Merge behavior: The restore process merges the backup with existing content:
  • Project conversations are merged (existing conversations remain)
  • Todo items are merged (existing todos remain)
  • Settings files (settings.json, config.json) are overwritten with backup versions
  • Lock files and temporary files are overwritten

Installation

Prerequisites

• Node.js (v18 or higher)
• GitHub CLI (gh) authenticated with gist permissions
• unzip command (pre-installed on macOS, may need installation on Linux)

Install via Package Manager (Recommended)

Using Bun (Fastest)

bun install -g @link-assistant/claude-profiles

Using npm

npm install -g @link-assistant/claude-profiles

After installation, the tool will be available globally as claude-profiles:

claude-profiles --help

Install from Source

1. Install GitHub CLI (if not already installed):

   # macOS
   brew install gh
   
   # Ubuntu/Debian
   sudo apt install gh
   
   # Other Linux distributions
   # Visit: https://github.com/cli/cli#installation

2. Authenticate with GitHub:

   gh auth login -s gist

   Follow the prompts and ensure you grant the gist scope for creating and managing gists.

3. Clone or download the tool:

   # Option A: Clone the repository
   git clone https://github.com/link-assistant/claude-profiles.git
   cd claude-profiles
   chmod +x claude-profiles.mjs
   
   # Option B: Download directly
   curl -O https://raw.githubusercontent.com/link-assistant/claude-profiles/main/claude-profiles.mjs
   chmod +x claude-profiles.mjs

4. Verify installation:

   # If installed via npm
   claude-profiles --list
      
   # If using from source
   ./claude-profiles.mjs --list

Usage

Basic Commands

List All Profiles

claude-profiles --list
# or
claude-profiles -l

Store Current Configuration

claude-profiles --store work
# or
claude-profiles --save work
# or
claude-profiles -s work

Restore a Profile

claude-profiles --restore personal
# or
claude-profiles -r personal

Delete a Profile

claude-profiles --delete old-profile
# or
claude-profiles -d old-profile

Verify Profile Integrity

claude-profiles --verify work
# or
claude-profiles -v work

Note: If you're using the tool from source instead of npm, prefix commands with ./ like ./claude-profiles.mjs --list

Advanced Features

Watch Mode

Automatically saves configuration changes to a profile with a 30-second throttle:

claude-profiles --watch work

# With verbose logging
claude-profiles --watch work --verbose

# With file logging
claude-profiles --watch work --log

# With custom log file
claude-profiles --watch work --log=/path/to/log-file.txt

Watch Mode Features:

• Monitors all Claude configuration files for changes
• Debounced saves (waits 2 seconds after last change)
• Minimum 30-second interval between saves to prevent excessive updates
• On macOS, also monitors Keychain credentials changes
• Graceful shutdown with Ctrl+C

Verbose Mode

Enable detailed logging for troubleshooting:

claude-profiles --store work --verbose

File Logging

Save all output to a log file:

# Auto-generated filename with timestamp
claude-profiles --store work --log

# Custom log file
claude-profiles --store work --log=claude-backup.log

Profile Names

Profile names must follow these rules:

• Only lowercase letters (a-z)
• Numbers (0-9)
• Hyphens (-)
• Examples: work, personal, client-1, dev-2024

Cross-Platform Support

macOS ↔ Linux Profile Compatibility

The tool automatically handles credential format conversion between platforms:

macOS → Linux

When restoring a macOS profile on Linux:

• Keychain credentials are converted to Linux format
• Credentials are saved to ~/.claude/.credentials.json
• Both old (underscore) and new (claudeAiOauth) formats are supported

Linux → macOS

When restoring a Linux profile on macOS:

• Linux credentials are converted to Keychain format
• Credentials are stored in macOS Keychain
• Legacy Linux formats are automatically upgraded

Credential Formats

The tool supports multiple credential formats:

1. Modern Format (with claudeAiOauth wrapper):

   {
     "claudeAiOauth": {
       "accessToken": "...",
       "refreshToken": "...",
       "expiresAt": "...",
       "scopes": ["user:inference"],
       "subscriptionType": "max"
     }
   }

2. Legacy Linux Format (underscore format):

   {
     "access_token": "...",
     "refresh_token": "...",
     "expiry_date": "...",
     "scopes": ["user:inference"],
     "subscriptionType": "max"
   }

All formats are automatically detected and converted as needed.

Error Handling & Edge Cases

GitHub Authentication Issues

Missing Gist Scope

Problem: Token lacks gist permissions

❌ Permission error creating gist

Solution:

gh auth refresh -s gist

Wrong Account

Problem: Gist owned by different GitHub account

❌ HTTP 409 - Gist cannot be updated

Solution:

# Check current account
gh auth status

# Re-login with correct account
gh auth login

Rate Limiting

Problem: Too many API requests

⚠️ GitHub API rate limit exceeded

Solution: Wait a few minutes and try again

Profile Issues

Missing Essential Files

Problem: Claude configuration incomplete

❌ Cannot create profile - essential files are missing

Solution:

• Ensure Claude is properly configured
• Use Claude at least once to generate config files
• Check that ~/.claude/ directory exists

Large Profiles

Problem: Profile exceeds GitHub's 10MB gist limit

❌ Profile is too large for GitHub Gist (>10MB)

Solution:

• Clean up ~/.claude/ directory
• Remove unnecessary files or cache
• Consider splitting into multiple profiles

Corrupted Profile

Problem: Profile verification fails

❌ Cannot restore profile - verification failed

Solution:

• Use --verify to check profile integrity
• Create a new backup with --store
• Check if the profile was created on a different platform

Platform-Specific Issues

macOS Keychain Access

Problem: Cannot access Keychain

⚠️ No credentials found in macOS Keychain

Solution:

• Ensure Claude has been used at least once
• Check Keychain Access app for "Claude Code-credentials"
• Grant terminal access to Keychain if prompted

Linux Missing unzip

Problem: unzip command not found

📦 The unzip command is required but not installed

Solution:

# Ubuntu/Debian
sudo apt-get install unzip

# Alpine
apk add unzip

# RHEL/CentOS
sudo yum install unzip

Network Issues

Connection Problems

Problem: Cannot connect to GitHub

🌐 Network error while accessing GitHub

Solution:

• Check internet connection
• Verify GitHub is accessible: ping github.com
• Check proxy settings if behind firewall

File System Issues

Permission Denied

Problem: Cannot read/write Claude files

📝 Permission denied

Solution:

# Check permissions
ls -la ~/.claude/

# Fix ownership (if needed)
chown -R $USER:$USER ~/.claude

Disk Space

Problem: No space for extraction

💾 No space left on device

Solution:

• Free up disk space
• Use a different temp directory: export TMPDIR=/path/to/space

Security Considerations

1. Gist Privacy: All profiles are stored as secret gists (not public)
2. Credential Security:
   • macOS: Stored securely in Keychain
   • Linux: Stored in user-only readable file
   • Transit: Base64 encoded (not encrypted)
3. GitHub Authentication: Uses GitHub CLI's secure token storage
4. File Permissions: Restored files maintain appropriate permissions

Troubleshooting

Enable Debug Output

# Verbose mode for detailed logging
claude-profiles --store work --verbose

# Save debug output to file
claude-profiles --store work --verbose --log=debug.log

Check GitHub Status

# Verify GitHub CLI authentication
gh auth status

# Test gist access
echo "test" | gh gist create -

# List your gists
gh gist list --limit 5

Manual Gist Management

# View gist contents
gh gist list | grep claude-profiles
gh gist view <GIST_ID>

# Delete gist entirely (removes all profiles)
gh gist delete <GIST_ID>

Common Solutions

1. First Time Setup:

   # 1. Install the tool (bun is faster)
   bun install -g @link-assistant/claude-profiles
   # or: npm install -g @link-assistant/claude-profiles
   
   # 2. Authenticate GitHub CLI
   gh auth login -s gist
   
   # 3. Create your first profile
   claude-profiles --store default
   
   # 4. List profiles to confirm
   claude-profiles --list

2. Switching Between Profiles:

   # Save current state
   claude-profiles --store current-work
      
   # Switch to different profile
   claude-profiles --restore personal
      
   # Later, switch back
   claude-profiles --restore current-work

3. Migrating to New Machine:

   # On old machine
   claude-profiles --store migration
   
   # On new machine (after installing and gh auth)
   bun install -g @link-assistant/claude-profiles
   claude-profiles --restore migration

Technical Details

Storage Format

• Profiles are stored as ZIP archives
• Archives are base64-encoded for gist compatibility
• Each profile is a separate file in the gist
• Gist description: "claude-profiles-backup"

File Structure in Archive

profile.zip.base64
├── .claude/                        # Complete directory structure
│   ├── .credentials.json          # Linux credentials (if present)
│   ├── ide/                       # IDE lock files
│   ├── plugins/                   # Plugin configurations
│   │   ├── config.json
│   │   └── repos/
│   ├── projects/                  # Project conversations
│   │   └── [project-folders]/     # Individual project histories
│   ├── settings.json              # Claude settings
│   ├── shell-snapshots/           # Shell session snapshots
│   ├── statsig/                   # Usage statistics
│   └── todos/                     # Todo items
├── .claude.json                   # Main configuration
├── .claude.json.backup            # Configuration backup
└── .macos.credentials.json        # macOS Keychain export (see note below)

macOS Credentials Handling

Important Note about .macos.credentials.json:

• This is an internal file created by the tool, not a Claude system file
• It only exists within the backup archive stored on GitHub Gist
• Purpose: Exports macOS Keychain credentials for cross-platform compatibility
• On restore:
  • To macOS: Credentials are restored directly to Keychain (file is not created on disk)
  • To Linux: Credentials are converted and saved as ~/.claude/.credentials.json
• This file never appears in your local filesystem on macOS - credentials always stay in Keychain

Dependencies

The tool uses dynamic loading via use-m for zero-install dependencies:

• [email protected] - Shell command execution
• [email protected] - CLI argument parsing
• [email protected] - ZIP archive creation

License

This project is released into the public domain under The Unlicense. See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests at: https://github.com/link-assistant/claude-profiles

Support

For issues, questions, or feature requests, please open an issue on GitHub: https://github.com/link-assistant/claude-profiles/issues