relay

A lightweight CLI tool for switching between multiple Claude Code accounts instantly.

Platform Support

| Platform | Credential Storage | |----------|--------------------| | macOS | Keychain (Claude Code-credentials) | | Linux / WSL | ~/.claude/.credentials.json | | Windows | %USERPROFILE%\.claude\.credentials.json |

Requirements

• claude CLI installed
• macOS / Linux / WSL: python3 available
• Windows: PowerShell 5.1+ (built into Windows 10/11)

Installation

npx (no install required)

Run once without installing anything permanently:

npx @dst-justin/relay install

This copies the relay script to /usr/local/bin/relay (or ~/bin/relay as fallback). After that, use relay directly.

npm (global install — recommended)

Requires Node.js 16+. Installs the relay command globally:

npm install -g @dst-justin/relay

To update later:

npm update -g @dst-justin/relay
# or from inside relay:
relay update

macOS / Linux / WSL (manual, no Node.js)

git clone https://github.com/darkstar1227/relay.git
cd relay

# Make the script executable
chmod +x relay

# Install (copies script to /usr/local/bin)
./relay install

This copies the script to /usr/local/bin/relay (falls back to ~/bin/relay if permissions are restricted).

Verify permissions

ls -l $(which relay)
# expected: -rwxr-xr-x ... or lrwxr-xr-x ...

ls -la ~/.claude-relay/
# expected: drwx------  ~/.claude-relay/
# expected: drwx------  ~/.claude-relay/credentials/

If any permissions are wrong:

chmod 700 ~/.claude-relay ~/.claude-relay/credentials
chmod 600 ~/.claude-relay/credentials/*.json

Windows (CMD / PowerShell, manual)

If you prefer not to use npm, clone the repo and add it to PATH manually.

git clone https://github.com/darkstar1227/relay.git
cd relay

Add to PATH permanently:

$dir = (Get-Location).Path
[Environment]::SetEnvironmentVariable(
    "PATH",
    "$([Environment]::GetEnvironmentVariable('PATH','User'));$dir",
    "User"
)

Restart your terminal after running this.

Allow the script to execute (first time only):

Unblock-File .\relay.ps1

Verify:

relay help

Quick Start

# Add your first account (opens browser — must run outside Claude Code)
relay add personal

# Add a second account
relay add work

# Switch accounts
relay 2        # by index
relay work     # by name

Usage Inside Claude Code

Prefix commands with ! to run them inline:

| Command | Description | |---------|-------------| | !relay | Account menu with 5-hour usage | | !relay 2 | Switch to account #2 | | !relay work | Switch to account named "work" | | !relay status | Detailed usage for current account |

Account Management

| Command | Description | |---------|-------------| | relay add <name> | Add account via browser login | | relay add-force <name> | Force re-login for existing account | | relay save <name> | Save current login state as a named account | | relay rename <old> <new> | Rename an account | | relay list | Full list with weekly usage | | relay list --no-usage | List without querying the API | | relay remove <name> | Delete an account | | relay sessions | Show all Claude Code sessions | | relay version | Show current version | | relay update | Check GitHub releases and update to the latest version | | relay uninstall | Remove relay and all account data (macOS/Linux only) | | relay autoswitch config | Interactive setup wizard | | relay autoswitch start | Install and start background daemon | | relay autoswitch stop | Stop and remove daemon | | relay autoswitch status | Daemon state and per-account thresholds | | relay autoswitch log | Recent auto-switch history |

Autoswitch

relay can automatically switch accounts when a 5-hour usage threshold is hit.

Setup:

relay autoswitch config   # interactive wizard
relay autoswitch start    # install daemon (launchd / systemd / cron)
relay autoswitch status   # verify it's running

Config file (~/.claude-relay/autoswitch.json):

{
  "order": ["work", "personal", "backup"],
  "thresholds": { "work": 70, "personal": 80 },
  "poll": { "low_minutes": 10, "high_minutes": 2, "high_threshold": 50 }
}

• Only accounts listed in order with a thresholds entry participate.
• No config file = autoswitch disabled entirely.
• Manual switches (!relay work) are respected until that account hits its threshold.
• If all accounts are over threshold, relay switches to the least-used one.

How It Works

relay stores a snapshot of each account's OAuth credentials in ~/.claude-relay/credentials/. Switching writes the target account's credentials back into the store that Claude Code reads from.

Sessions live in ~/.claude/projects/ and are shared across all accounts — after switching, use claude -c to resume the last session or claude --resume <id> to pick a specific one.

Note: relay add must be run in a regular Terminal, not inside Claude Code, because the browser login flow is not available inside an active session.

Files

~/.claude-relay/
├── credentials/   # Per-account credential snapshots (chmod 700 on Unix)
├── meta/          # Per-account email cache
└── current        # Name of the active account

Windows-specific files

| File | Purpose | |------|---------| | relay.ps1 | Full PowerShell implementation | | relay.cmd | Thin CMD wrapper — delegates to relay.ps1 |

Changelog

v2.1.1 — 2026-06-24

• Display current version and latest version at the end of list, status, relay (menu), sessions, and help commands
• Background version check (24h cache) — non-blocking, never slows down output
• relay update now detects original install method: uses npm install -g for npm installs, git pull for git clones, and direct GitHub download for bare script copies
• npm install -g post-install script automatically patches ~/.bashrc, ~/.zshrc, ~/.profile, and fish config.fish if the npm bin dir is missing from PATH

v2.1.3 — 2026-06-24

• relay autoswitch with no subcommand: auto-routes to config wizard (first time) or status panel (already configured)
• Autoswitch status and log panels now show version info and update notice at the bottom
• Status panel shows available commands inline

v2.1.2 — 2026-06-24

• Improve autoswitch config wizard: 3-step flow with numbered account list, space-separated number input for order, visual chain preview (work → personal → (cycle)), and summary after save
• relay update now writes the live-fetched version to cache immediately, so display commands reflect the latest version without waiting 24h

v2.1.0 — 2026-06-24

• Upgraded GitHub Actions workflow to actions/checkout@v6 and actions/setup-node@v6 (Node 24 runtime, removes Node 20 deprecation warning)

v2.0.2 — 2026-06-23

• Skip npm install during relay update when already on the latest version or when version check fails