A production-ready system for running Claude Code with OpenRouter backend on macOS, featuring automatic system startup, secure configuration management, and single-instance guarantees.

📋 What's Included

Core Scripts

File	Purpose
`run-claude-openrouter.sh`	Main launcher with all features (setup, daemon, status)
`config-manager.sh`	Secure configuration storage and loading
`ccr-config.sh`	CLI utility for managing API keys
`com.musistudio.ccr.plist`	LaunchAgent for system auto-start

Documentation

File	Purpose
`QUICKSTART.md`	5-minute setup guide (start here!)
`SETUP.md`	Comprehensive setup and usage guide
`README.md`	This file

✨ Key Features

🔒 Secure Configuration

API keys stored safely in ~/.claude-code-router/.env with 600 permissions
Auto-loaded on every session
Masked output when displaying configuration

🚀 Automatic System Startup

Installs LaunchAgent for system boot auto-start
Survives system reboots without manual intervention
Single instance guarantee - only one CCR process runs

⚡ Easy to Use

One-line setup: export OPENROUTER_API_KEY='...' && ./run-claude-openrouter.sh --setup
One-line usage: ./run-claude-openrouter.sh --code
Configuration auto-loads in every session

📊 Built-in Diagnostics

Health checks and smoke tests
Status reporting with masked configuration display
Real-time log viewing
Configuration validation

🚀 Quick Start

1. Setup (First Time Only)

export OPENROUTER_API_KEY='sk-or-v1-your-key-here'
./run-claude-openrouter.sh --setup

2. Start Coding

./run-claude-openrouter.sh --code

That's it! CCR will auto-start on system reboot from now on.

3. Verify It Works

./run-claude-openrouter.sh --status

See QUICKSTART.md for more details.

📖 Usage Guide

Main Commands

# First-time setup (configures API key + LaunchAgent)
./run-claude-openrouter.sh --setup

# Start coding (loads config + starts CCR + launches Claude Code)
./run-claude-openrouter.sh --code

# Start as daemon (background service)
./run-claude-openrouter.sh --daemon

# Show current status
./run-claude-openrouter.sh --status

# Stop the service
./run-claude-openrouter.sh --stop

# Tail logs in real-time
./run-claude-openrouter.sh --logs

# Validate configuration
./run-claude-openrouter.sh --validate

# Uninstall (removes LaunchAgent + stops service)
./run-claude-openrouter.sh --uninstall

Configuration Management

# Show all configured API keys (masked)
./ccr-config.sh show

# Set API key
./ccr-config.sh set-key openrouter "sk-or-v1-..."

# Validate configuration
./ccr-config.sh validate

# Show configuration directory
./ccr-config.sh path

# Reset all configuration
./ccr-config.sh reset

🏗️ Architecture

Directory Structure

~/.claude-code-router/
├── .env                           # Configuration (API keys)
├── ccr.log                        # Stdout logs
├── ccr-error.log                  # Stderr logs
├── claude-code-router.log         # Detailed logs
└── .claude-code-router.pid        # Process ID

Security Model

File Permissions: Config files use 600 (owner only)
No History: API keys not stored in shell history
Masked Display: Configuration display masks API keys
Environment Isolation: LaunchAgent gets fresh environment each session

Auto-Start Mechanism

LaunchAgent plist installed at ~/Library/LaunchAgents/com.musistudio.ccr.plist
macOS loads it at user login
run-claude-openrouter.sh sources .env file to load config
CCR daemon starts with OpenRouter backend
Automatically restarts if it crashes

🔧 Troubleshooting

Issue: Setup fails with "OPENROUTER_API_KEY not set"

Solution:

export OPENROUTER_API_KEY='sk-or-v1-your-key'
./run-claude-openrouter.sh --setup

Issue: CCR not starting automatically after reboot

Check LaunchAgent status:

./run-claude-openrouter.sh --status
launchctl list com.musistudio.ccr

If needed, reload LaunchAgent:

launchctl unload ~/Library/LaunchAgents/com.musistudio.ccr.plist
launchctl load ~/Library/LaunchAgents/com.musistudio.ccr.plist

Issue: Service responding slowly or timing out

Check logs:

./run-claude-openrouter.sh --logs

Restart service:

./run-claude-openrouter.sh --stop
sleep 2
./run-claude-openrouter.sh --daemon

Issue: Multiple CCR instances running

Kill all and restart:

pkill -f "ccr start"
sleep 2
./run-claude-openrouter.sh --daemon

📚 Advanced Usage

Manual Configuration

If you prefer manual setup:

mkdir -p ~/.claude-code-router
chmod 700 ~/.claude-code-router

cat > ~/.claude-code-router/.env << 'EOF'
OPENROUTER_API_KEY='sk-or-v1-your-key'
ANTHROPIC_API_KEY='placeholder'
EOF

chmod 600 ~/.claude-code-router/.env

Custom Port

Edit the com.musistudio.ccr.plist file and add environment variables:

<key>EnvironmentVariables</key>
<dict>
  <key>CCR_PORT</key>
  <string>3457</string>
</dict>

Debug Mode

Enable debug output:

DEBUG=1 ./run-claude-openrouter.sh --daemon

🔐 Security Considerations

API Key Safety

Never commit .env to version control
Use .gitignore to exclude ~/.claude-code-router/
Keys are only readable by the owner (600 permissions)
LaunchAgent only executes for the logged-in user

Network Security

CCR listens on 127.0.0.1:3456 (localhost only)
No exposure to network unless explicitly configured
HTTPS to OpenRouter API (encrypted in transit)

📊 Monitoring

View Logs

# Real-time tail
./run-claude-openrouter.sh --logs

# View last N lines
tail -50 ~/.claude-code-router/claude-code-router.log

# Search logs
grep ERROR ~/.claude-code-router/claude-code-router.log

Check Status

./run-claude-openrouter.sh --status
ccr status
ps aux | grep ccr

Performance

# Check process memory/CPU
ps aux | grep ccr

# Monitor in real-time
top -p $(pgrep -f "ccr start")

🧹 Maintenance

Backup Configuration

cp ~/.claude-code-router/.env ~/.claude-code-router/.env.backup

Update API Key

./ccr-config.sh set-key openrouter "sk-or-v1-new-key"

Clean Old Logs

# The system auto-rotates logs, but you can manually clean old ones
rm -f ~/.claude-code-router/ccr.log.*

🚀 Uninstall

To remove the system completely:

./run-claude-openrouter.sh --uninstall

This will:

Stop the CCR service
Remove LaunchAgent
Preserve configuration directory for recovery

To restore, run setup again.

📞 Support

Helpful Commands for Troubleshooting

# Check everything
./run-claude-openrouter.sh --status
./run-claude-openrouter.sh --validate

# View diagnostic information
./ccr-config.sh show
./run-claude-openrouter.sh --logs

# Manual checks
ccr status
launchctl list com.musistudio.ccr
ls -la ~/Library/LaunchAgents/com.musistudio.ccr.plist

📖 Documentation

QUICKSTART.md - 5-minute setup guide (start here!)
SETUP.md - Comprehensive documentation
config-manager.sh - Configuration API documentation

🔗 Resources

📝 License

This system is provided as-is. Ensure you comply with OpenRouter and Anthropic terms of service.

🎯 Summary

This is a production-ready, battle-tested system for:

✅ Securing API keys ✅ Auto-starting services ✅ Running single instances ✅ Easy diagnostics ✅ Zero manual intervention after setup

Get started in 5 minutes: See QUICKSTART.md