Metadata-Version: 2.4
Name: multi-claude
Version: 1.0.32
Summary: Run multiple Claude CLI accounts with shared settings, plugins, marketplace sync, and backup/restore
Author: Gyanesh Kumar
License: MIT
Project-URL: Homepage, https://github.com/ghackk/claude-multi-account
Project-URL: Repository, https://github.com/ghackk/claude-multi-account
Keywords: claude,claude-code,claude-cli,multi-account,anthropic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

<h1>claude-multi-account</h1>

<p><strong>Run multiple Claude CLI accounts with shared settings, plugins, marketplace sync, and backup/restore.</strong></p>

<p>
  <a href="https://www.npmjs.com/package/@ghackk/multi-claude"><img src="https://img.shields.io/npm/v/@ghackk/multi-claude?color=cb3837&label=npm" alt="npm"></a>
  <a href="https://pypi.org/project/multi-claude/"><img src="https://img.shields.io/pypi/v/multi-claude?color=3776ab&label=pip" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey" alt="Platform">
  <a href="https://github.com/ghackk/claude-multi-account/stargazers"><img src="https://img.shields.io/github/stars/ghackk/claude-multi-account?style=social" alt="GitHub Stars"></a>
</p>

<img src="images/demo.gif" alt="multi-claude demo" width="600">

</div>

---

## Why?

### Automatic application updates (v1.0.29 working branch)

Each menu launch starts a nonblocking check of `https://pair.ghackk.com/updates/stable.json`. If the server is unavailable, the updater checks the signed `stable.json` asset on the latest GitHub release. The application keeps running while the check happens. Failed checks back off for 15 minutes; offline operation uses the last working installation.

The manifest is signed with a pinned Ed25519 key and contains a version, expiry, Node requirement, exact archive size and SHA-256 hash. Downloads try the server-hosted archive, then the GitHub release archive. On Windows the transport fallbacks are Node HTTPS, curl, then PowerShell; macOS/Linux use Node HTTPS then curl. All paths require HTTPS. Invalid signatures, expired manifests, corrupt archives and downgrades are rejected.

Updates install application files into `~/.multi-claude-updates/versions/`, then atomically switch the selected version after validation. The next menu launch uses that version. The prior installed package and cached version remain available if a cached release is incomplete. Account profiles, credentials, backups and usage history are never part of the update directory. No administrator access, package-manager switching or lifecycle scripts are needed.

This updates the **running application**, not npm/pip/Homebrew/Scoop's installed-version records. `multi-claude --version` reports the selected application version. `multi-claude --update-status` shows the base version, selected version and last result; `multi-claude --update-now` waits for a check. Set `MULTI_CLAUDE_AUTO_UPDATE=0` to disable background checks. Explicit checks remain available.

Versions before 1.0.29 need a one-time upgrade to obtain this updater. A source Git checkout is no longer silently pulled by the pip launcher; application updates follow the signed release feed.

Maintainers publish a normal `npm pack --ignore-scripts` archive as a GitHub release asset. The release helper `local-usage/publish-channels.py VERSION` also calls `local-usage/publish-update-feed.py VERSION`, uploading the archive to the server, checking its hash remotely, atomically activating the manifest, and mirroring the signed manifest on GitHub. Signing credentials stay outside the public repository. Existing versioned archives are immutable. Renew the manifest before its 89-day expiry if no new release is made; clients remain usable offline after expiry.

<div align="center">
<img src="images/12-before-after.png" alt="Before vs After" width="700">
</div>

<br>

Claude CLI stores all config in a single `~/.claude/` directory — so you're locked to **one account at a time**. Switching means logging out, logging in, and losing your settings.

**claude-multi-account** fixes this:

- **Isolated profiles** — each account gets its own config directory, no conflicts
- **Shared settings** — define MCP servers, env vars, plugins, and CLAUDE.md once — auto-applied everywhere
- **Plugin & marketplace management** — enable plugins globally or per-account, browse marketplace indexes
- **Direct launch** — run `claude-work` or `claude-personal` directly from any terminal, no menu needed
- **Cloud backup & restore** — securely sync all profiles to the cloud and restore on any machine
- **One command** — launch any account instantly from an interactive menu

---

## Get Started in 10 Seconds

<div align="center">
<img src="images/15-quick-start.png" alt="Quick Start" width="600">
</div>

---

## Features

<table>
<tr>
<td width="50%">

**Multi-Account Management**<br>
Create, launch, rename, and delete independent Claude CLI profiles

</td>
<td width="50%">

**Shared MCP & Settings**<br>
Define MCP servers, env vars, and preferences once — sync to all accounts

</td>
</tr>
<tr>
<td>

**Plugins & Marketplace**<br>
Enable/disable plugins globally or per-account, browse and manage marketplace indexes

</td>
<td>

**Global CLAUDE.md**<br>
Write instructions and skills that apply across every account

</td>
</tr>
<tr>
<td>

**Backup & Restore**<br>
Timestamped local archives of all accounts and configs with one click

</td>
<td>

**Export / Import Profiles**<br>
Copy a profile between machines as a single base64 token — credentials, settings, and launcher included

</td>
</tr>
<tr>
<td>

**Cloud Backup & Restore**<br>
Securely sync all profiles to the cloud — restore on any machine with a single command

</td>
<td>

**Direct Profile Launch**<br>
Each profile is auto-registered on PATH — run `claude-work` directly from any terminal

</td>
</tr>
<tr>
<td>

**Auto Dependency Detection**<br>
Detects and offers to install missing dependencies (curl, jq, etc.) on first run

</td>
<td>

**Run from Repo**<br>
Add the repo to your PATH — `git pull` instantly updates the menu, no manual copying

</td>
</tr>
</table>

---

## Install

<div align="center">
<img src="images/06-install.png" alt="Install methods" width="600">
</div>

<br>

Pick any method — they all give you the `claude-menu` (or `multi-claude`) command.

### One-liner (recommended)

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/ghackk/claude-multi-account/master/install.sh | bash
```

```powershell
# Windows (PowerShell)
irm https://raw.githubusercontent.com/ghackk/claude-multi-account/master/install.ps1 | iex
```

### npm

```bash
npm install -g @ghackk/multi-claude
```

### pip

```bash
pip install multi-claude
```

### Homebrew (macOS / Linux)

```bash
brew install ghackk/tap/multi-claude
```

### Scoop (Windows)

```powershell
scoop bucket add multi-claude https://github.com/ghackk/scoop-multi-claude
scoop install multi-claude
```

### AUR (Arch Linux)

```bash
yay -S multi-claude
```

### Manual (git clone)

```bash
# Linux / macOS
git clone https://github.com/ghackk/claude-multi-account.git ~/claude-multi-account
bash unix/install.sh
```

```powershell
# Windows
git clone https://github.com/ghackk/claude-multi-account.git $HOME\claude-multi-account
[Environment]::SetEnvironmentVariable("PATH", "$HOME\claude-multi-account;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User")
```

Then open a new terminal and run `claude-menu`.

---

## Menu Overview

### Main Menu

<div align="center">
<img src="images/01-main-menu.png" alt="Main Menu" width="500">
</div>

```
======================================
       Claude Account Manager
======================================
  Current Accounts:

  1. claude-work     [logged in]   (last used: 02 Mar 2026 10:30 AM)
  2. claude-personal [logged in]   (last used: 01 Mar 2026 08:15 PM)

======================================
  1. List Accounts
  2. Create New Account
  3. Launch Account
  4. Rename Account
  5. Delete Account
  6. Backup Sessions (Local)
  7. Restore Sessions (Local)
  8. Shared Settings (MCP/Skills)
  9. Plugins & Marketplace
  E. Export Profile (Token)
  I. Import Profile (Token)
  C. Cloud Backup
  R. Cloud Restore
  0. Exit
======================================
```

### Shared Settings (Option 8)

<div align="center">
<img src="images/05-shared-settings.png" alt="Shared Settings" width="500">
</div>

Manage universal settings applied to all accounts on launch:

| Option | Action |
|--------|--------|
| 1 | Edit MCP + Settings (opens in editor) |
| 2 | Edit Skills/Instructions (CLAUDE.md) |
| 3 | View current shared settings |
| 4 | Sync shared settings to ALL accounts |
| 5 | Show MCP server list |
| 6 | Reset shared settings |

### Plugins & Marketplace (Option 9)

Browse marketplace indexes and manage plugins across accounts:

| Option | Action |
|--------|--------|
| 1 | Enable plugin for ALL accounts |
| 2 | Enable plugin for one account |
| 3 | Disable plugin (shared) |
| 4 | Disable plugin (one account) |
| 5 | Browse marketplace plugins |
| 6 | Marketplace Management (add/remove/sync) |

### Export / Import Profile (Options E & I)

<div align="center">
<img src="images/07-export-profile.png" alt="Export Profile" width="500">
</div>

Transfer a profile between machines using a copy-pasteable base64 token:

| Option | Action |
|--------|--------|
| E | Export a profile — generates a compact token (~5 KB) containing credentials, settings, and launcher |
| I | Import a profile — paste the token to restore the account on any machine |

The token bundles only essentials (credentials, settings, CLAUDE.md, launcher) — not cache or conversation history.

### Cloud Backup & Restore (Options C & R)

<div align="center">
<img src="images/04-cloud-backup.png" alt="Cloud Backup" width="500">
</div>

Sync all profiles to the cloud and restore on any machine:

| Option | Action |
|--------|--------|
| C | Cloud Backup — select profiles and optional folders (shared settings, plugins, etc.) to upload securely |
| R | Cloud Restore — enter your route key to download and restore all profiles on a new machine |

Profiles are automatically registered on PATH after restore, so you can run `claude-work` immediately.

### Direct Profile Launch

<div align="center">
<img src="images/03-direct-launch.png" alt="Direct Launch" width="500">
</div>

Every profile you create is automatically available as a command:

```bash
# No need to open the menu — just run the profile name directly
claude-work
claude-personal
```

On **Linux/macOS/Termux**, symlinks are created in `~/.local/bin/`. On **Windows**, the accounts directory is added to your user PATH. Profiles created, imported, or restored are all registered automatically.

---

## How It Works

<div align="center">
<img src="images/14-how-it-works.png" alt="How it works" width="600">
</div>

```
┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  You pick    │ ───> │  Shared settings │ ───> │  Claude CLI     │
│  an account  │      │  + plugins are   │      │  launches with  │
│  from menu   │      │  merged in       │      │  isolated config│
└─────────────┘      └──────────────────┘      └─────────────────┘
```

Each account gets its own config directory (`~/.claude-<name>`). On every launch, shared settings from `~/claude-shared/` are deep-merged into the account — MCP servers, env vars, preferences, plugins, marketplace indexes, and CLAUDE.md instructions all stay in sync.

### Merge Strategy

Settings are **deep-merged** with shared settings winning on conflict:

| Scenario | Result |
|----------|--------|
| Key exists only in account | Kept |
| Key exists only in shared | Added |
| Key exists in both (simple value) | Shared wins |
| Key exists in both (nested object) | Recursively merged |

For `CLAUDE.md`, shared content is inserted between auto-managed markers at the top. Account-specific instructions below the markers are preserved.

---

## Folder Structure

<div align="center">
<img src="images/08-folder-structure.png" alt="Folder Structure" width="500">
</div>

```
~/
├── claude-multi-account/      # Git repo (can be added to PATH directly)
│   ├── claude-menu.ps1        # Windows menu script
│   ├── claude-menu.bat        # Windows launcher
│   ├── windows/               # Windows-specific scripts
│   └── unix/                  # Linux/macOS scripts
│
├── claude-accounts/           # Account launchers (auto-created)
│   ├── claude-work.bat/.sh    # Account launcher
│   └── claude-personal.bat/.sh
│
├── claude-shared/             # Shared config (applied to all accounts)
│   ├── settings.json          # MCP servers, env vars, preferences, enabledPlugins, extraKnownMarketplaces
│   ├── CLAUDE.md              # Global instructions & skills
│   └── plugins/               # Shared plugin & marketplace data
│       └── marketplaces/      # Cached marketplace indexes
│
├── claude-backups/            # Timestamped backup archives
│
├── .claude-work/              # Account: work (auto-created)
├── .claude-personal/          # Account: personal (auto-created)
└── .claude-<name>/            # Account: <name>
```

---

## Documentation

- **[Installation Guide](docs/installation.md)** — setup for all platforms
- **[Usage Guide](docs/usage.md)** — full walkthrough of every feature

---

## Platform Support

<div align="center">
<img src="images/13-platforms.png" alt="Platform Support" width="600">
</div>

## Requirements

- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) installed and available in PATH
- **Windows**: PowerShell 5.1+ (dependencies auto-detected via winget/scoop)
- **Linux/macOS**: Bash 3.2+ (the macOS system Bash works). Dependencies including `curl`, `jq`, Python 3, and Node.js are checked on first run.
- **Termux**: Supported — dependencies installed via `pkg`

---

## Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

---

## Credits

Built by **[Gyanesh Kumar](https://github.com/ghackk)**

---

## License

[MIT](LICENSE)


## Usage history (v1.0.26)

Choose **U** in either menu to open the login-protected hosted dashboard, enable/disable reporting, or merge another PC's history. Usage is keyed by normalized email and reply ID: renaming `claude-zf` to `claude-zafff`, creating another profile for the same email, or reporting from a laptop with empty history never resets the server's all-time totals. Restored copies are deduplicated.

The menu installs background session hooks, launcher triggers, and a 15-minute Windows scheduled task, macOS LaunchAgent, or Linux cron entry. Requires Node.js 22.13+. The dashboard shows UTC periods, model/month/device totals, account limits, and Claude Code's stats-cache comparison. [Usage tracking details](docs/usage-tracking.md).

macOS supports both Apple Silicon and Intel, including profile-specific Keychain credentials for account transfer and usage limits. Account renaming preserves the Keychain login. npm installation does not require lifecycle scripts, including with npm 12's defaults. Run `multi-claude` after installation to set up launchers and usage history.
