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

$3

- 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

$3

- ~/.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)

$3

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

$3

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

$3

#### Using Bun (Fastest)
``bash
bun install -g @link-assistant/claude-profiles
`

#### Using npm
`bash
npm install -g @link-assistant/claude-profiles
`

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

`bash
claude-profiles --help
`

$3

1. Install GitHub CLI (if not already installed):
`bash
# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Other Linux distributions
# Visit: https://github.com/cli/cli#installation
`

2. Authenticate with GitHub:
`bash
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:
`bash
# 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:
`bash
# If installed via npm
claude-profiles --list

# If using from source
./claude-profiles.mjs --list
`

Usage

$3

#### List All Profiles
`bash
claude-profiles --list


or


claude-profiles -l
`

#### Store Current Configuration
`bash
claude-profiles --store work


or

claude-profiles --save work

or

claude-profiles -s work
`

#### Restore a Profile
`bash
claude-profiles --restore personal


or


claude-profiles -r personal
`

#### Delete a Profile
`bash
claude-profiles --delete old-profile


or


claude-profiles -d old-profile
`

#### Verify Profile Integrity
`bash
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

$3

#### Watch Mode
Automatically saves configuration changes to a profile with a 30-second throttle:
`bash
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:
`bash
claude-profiles --store work --verbose
`

#### File Logging
Save all output to a log file:
`bash


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

$3

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

$3

The tool supports multiple credential formats:

1. Modern Format (with claudeAiOauth wrapper):
`json
{
"claudeAiOauth": {
"accessToken": "...",
"refreshToken": "...",
"expiresAt": "...",
"scopes": ["user:inference"],
"subscriptionType": "max"
}
}
`

2. Legacy Linux Format (underscore format):
`json
{
"access_token": "...",
"refresh_token": "...",
"expiry_date": "...",
"scopes": ["user:inference"],
"subscriptionType": "max"
}
`

All formats are automatically detected and converted as needed.

Error Handling & Edge Cases

$3

#### Missing Gist Scope
Problem: Token lacks gist permissions
`
❌ Permission error creating gist
`
Solution:
`bash
gh auth refresh -s gist
`

#### Wrong Account
Problem: Gist owned by different GitHub account
`
❌ HTTP 409 - Gist cannot be updated
`
Solution:
`bash


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

$3

#### 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

$3

#### 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:
`bash


Ubuntu/Debian

sudo apt-get install unzip

Alpine

apk add unzip

RHEL/CentOS

sudo yum install unzip
`

$3

#### 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

$3

#### Permission Denied
Problem: Cannot read/write Claude files
`
📝 Permission denied
`
Solution:
`bash


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

$3


`bash

Verbose mode for detailed logging

claude-profiles --store work --verbose

Save debug output to file

claude-profiles --store work --verbose --log=debug.log
`

$3

`bash

Verify GitHub CLI authentication

gh auth status

Test gist access

echo "test" | gh gist create -

List your gists

gh gist list --limit 5
`

$3

`bash

View gist contents

gh gist list | grep claude-profiles
gh gist view

Delete gist entirely (removes all profiles)

gh gist delete
`

$3

1. First Time Setup:
`bash
# 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:
`bash
# 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:
`bash
# 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

$3

- 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"

$3

`
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)
`

$3

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

$3


The tool uses dynamic loading via use-m for zero-install dependencies:
- command-stream@0.7.0 - Shell command execution
- yargs@17.7.2 - CLI argument parsing
- archiver@7.0.1` - 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