cc-swap 0.1.0

package/dist/cli.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { spawnSync } from "child_process";
+import path3 from "path";
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+
+// src/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+var HOME = process.env.CC_SWAP_HOME ?? homedir();
+var CLAUDE_DIR = process.env.CC_SWAP_CLAUDE_DIR ?? join(HOME, ".claude");
+var CC_SWAP_DIR = join(HOME, ".cc-swap");
+var ACCOUNTS_DIR = join(CC_SWAP_DIR, "claude-accounts");
+var CURRENT_FILE = join(CC_SWAP_DIR, ".current");
+var CONFIG_FILE = join(CC_SWAP_DIR, "config.json");
+
+// src/accounts.ts
+import fsPromises2 from "fs/promises";
+import path2 from "path";
+
+// src/validate.ts
+function validateName(name) {
+  if (!name) return "Name cannot be empty";
+  if (name.length > 50) return "Name must be 50 characters or fewer";
+  if (name.startsWith(".") || name.startsWith("-"))
+    return "Name cannot start with '.' or '-'";
+  if (!/^[a-zA-Z0-9_-]+$/.test(name))
+    return "Name can only contain letters, numbers, hyphens, and underscores";
+  return null;
+}
+
+// src/symlink.ts
+import fsPromises from "fs/promises";
+import path from "path";
+async function populateAccount(claudeDir, accountDir, syncItems) {
+  await fsPromises.mkdir(accountDir, { recursive: true, mode: 448 });
+  for (const item of syncItems) {
+    const source = path.join(claudeDir, item);
+    const link = path.join(accountDir, item);
+    const sourceExists = await fsPromises.access(source).then(() => true).catch(() => false);
+    if (!sourceExists) continue;
+    const linkExists = await fsPromises.access(link).then(() => true).catch(() => false);
+    if (linkExists) continue;
+    await fsPromises.symlink(source, link);
+  }
+}
+async function readCurrent(filePath) {
+  try {
+    const content = (await fsPromises.readFile(filePath, "utf-8")).trim();
+    return content || null;
+  } catch {
+    return null;
+  }
+}
+async function writeCurrent(filePath, name) {
+  await fsPromises.writeFile(filePath, name + "\n", { mode: 384 });
+}
+
+// src/accounts.ts
+async function listAccounts(accountsDir) {
+  try {
+    const entries = await fsPromises2.readdir(accountsDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort((a, b) => a.localeCompare(b, void 0, { sensitivity: "base" }));
+  } catch {
+    return [];
+  }
+}
+function nextAccount(current, accounts) {
+  if (accounts.length <= 1) return null;
+  const idx = accounts.indexOf(current);
+  return accounts[(idx + 1) % accounts.length];
+}
+async function addAccount(name, paths) {
+  const { claudeDir, ccSwitchDir, accountsDir, currentFile } = paths;
+  const nameErr = validateName(name);
+  if (nameErr) throw new Error(nameErr);
+  const accountsExist = await fsPromises2.access(accountsDir).then(() => true).catch(() => false);
+  if (!accountsExist) {
+    await fsPromises2.mkdir(accountsDir, { recursive: true, mode: 448 });
+    if (ccSwitchDir) {
+      await fsPromises2.chmod(ccSwitchDir, 448);
+    }
+  }
+  const target = path2.join(accountsDir, name);
+  const exists = await fsPromises2.access(target).then(() => true).catch(() => false);
+  if (exists) throw new Error(`Account '${name}' already exists`);
+  await populateAccount(claudeDir, target, paths.syncItems ?? []);
+  const current = await readCurrent(currentFile);
+  if (!current) {
+    await writeCurrent(currentFile, name);
+  }
+}
+async function switchAccount(name, paths) {
+  const nameErr = validateName(name);
+  if (nameErr) throw new Error(nameErr);
+  const { accountsDir, currentFile } = paths;
+  const target = path2.join(accountsDir, name);
+  const exists = await fsPromises2.access(target).then(() => true).catch(() => false);
+  if (!exists) throw new Error(`Account '${name}' does not exist`);
+  const current = await readCurrent(currentFile);
+  if (current === name) return `'${name}' is already active`;
+  await writeCurrent(currentFile, name);
+  return `Switched to: ${name}`;
+}
+async function removeAccount(name, paths) {
+  const nameErr = validateName(name);
+  if (nameErr) throw new Error(nameErr);
+  const { accountsDir, currentFile } = paths;
+  const target = path2.join(accountsDir, name);
+  const exists = await fsPromises2.access(target).then(() => true).catch(() => false);
+  if (!exists) throw new Error(`Account '${name}' does not exist`);
+  const current = await readCurrent(currentFile);
+  if (current === name) {
+    throw new Error(`Cannot remove '${name}' \u2014 it is currently active. Switch to another account first.`);
+  }
+  const all = await listAccounts(accountsDir);
+  if (all.length <= 1) {
+    throw new Error(`Cannot remove '${name}' \u2014 it is the last remaining account.`);
+  }
+  await fsPromises2.rm(target, { recursive: true, force: true });
+}
+
+// src/items.ts
+import fsPromises3 from "fs/promises";
+var DEFAULT_ITEMS = [
+  "agents",
+  "commands",
+  "file-history",
+  "hooks",
+  "plugins",
+  "projects",
+  "rules",
+  "session-env",
+  "sessions",
+  "settings.json",
+  "skills",
+  "tasks"
+];
+var DEFAULT_CONFIG = {
+  syncItems: [...DEFAULT_ITEMS],
+  autoContinue: true
+};
+async function loadConfig(configFile) {
+  try {
+    const raw = await fsPromises3.readFile(configFile, "utf-8");
+    const parsed = JSON.parse(raw);
+    return {
+      syncItems: Array.isArray(parsed.syncItems) ? parsed.syncItems : [...DEFAULT_ITEMS],
+      autoContinue: parsed.autoContinue !== false
+    };
+  } catch {
+    const config = { ...DEFAULT_CONFIG, syncItems: [...DEFAULT_ITEMS] };
+    const dir = configFile.substring(0, configFile.lastIndexOf("/"));
+    await fsPromises3.mkdir(dir, { recursive: true, mode: 448 }).catch(() => void 0);
+    await saveConfig(configFile, config);
+    return config;
+  }
+}
+async function saveConfig(configFile, config) {
+  await fsPromises3.writeFile(configFile, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+}
+
+// src/cli.ts
+function launchClaude(accountDir, config) {
+  if (process.env.CC_SWAP_NO_LAUNCH) return;
+  const args = config.autoContinue ? ["--continue"] : [];
+  console.log(`Launching Claude Code (config: ${accountDir})...
+`);
+  const result = spawnSync("claude", args, {
+    stdio: "inherit",
+    env: { ...process.env, CLAUDE_CONFIG_DIR: accountDir }
+  });
+  process.exit(result.status ?? 0);
+}
+var program = new Command();
+program.name("cc-swap").description("Switch between multiple Claude Code accounts").version("0.1.0");
+program.action(async () => {
+  const config = await loadConfig(CONFIG_FILE);
+  const accounts = await listAccounts(ACCOUNTS_DIR);
+  if (accounts.length === 0) {
+    console.log("No accounts found. Run 'cc-swap add <name>' to get started.");
+    return;
+  }
+  const current = await readCurrent(CURRENT_FILE);
+  if (!current) {
+    console.log("No active account. Run 'cc-swap switch <name>' to activate one.");
+    return;
+  }
+  const next = nextAccount(current, accounts);
+  if (!next) {
+    console.log(`Using account: ${current}`);
+    launchClaude(path3.join(ACCOUNTS_DIR, current), config);
+    return;
+  }
+  await switchAccount(next, {
+    claudeDir: CLAUDE_DIR,
+    accountsDir: ACCOUNTS_DIR,
+    currentFile: CURRENT_FILE
+  });
+  console.log(`Switched: ${current} \u2192 ${next}`);
+  launchClaude(path3.join(ACCOUNTS_DIR, next), config);
+});
+program.command("add <name>").description("Add a new account (populated with symlinks to ~/.claude)").action(async (name) => {
+  try {
+    const config = await loadConfig(CONFIG_FILE);
+    await addAccount(name, {
+      claudeDir: CLAUDE_DIR,
+      ccSwitchDir: CC_SWAP_DIR,
+      accountsDir: ACCOUNTS_DIR,
+      currentFile: CURRENT_FILE,
+      syncItems: config.syncItems
+    });
+    console.log(`Added account '${name}'.`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.command("switch <name>").description("Switch to a specific account and launch Claude Code").action(async (name) => {
+  try {
+    const config = await loadConfig(CONFIG_FILE);
+    const msg = await switchAccount(name, {
+      claudeDir: CLAUDE_DIR,
+      accountsDir: ACCOUNTS_DIR,
+      currentFile: CURRENT_FILE
+    });
+    console.log(msg);
+    if (!msg.includes("already active")) {
+      launchClaude(path3.join(ACCOUNTS_DIR, name), config);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.command("list").description("List all accounts").action(async () => {
+  const accounts = await listAccounts(ACCOUNTS_DIR);
+  if (accounts.length === 0) {
+    console.log("No accounts found. Run 'cc-swap add <name>' to get started.");
+    return;
+  }
+  const current = await readCurrent(CURRENT_FILE);
+  for (const name of accounts) {
+    const marker = name === current ? "* " : "  ";
+    const label = name === current ? " (active)" : "";
+    console.log(`${marker}${name}${label}`);
+  }
+});
+program.command("remove <name>").description("Remove an account").option("-f, --force", "Skip confirmation prompt").action(async (name, opts) => {
+  try {
+    if (!opts.force) {
+      const rl = createInterface({ input, output });
+      const answer = await rl.question(
+        `Remove account '${name}'? This will delete all its data. (y/N) `
+      );
+      rl.close();
+      if (answer.toLowerCase() !== "y") {
+        console.log("Cancelled.");
+        return;
+      }
+    }
+    await removeAccount(name, {
+      accountsDir: ACCOUNTS_DIR,
+      currentFile: CURRENT_FILE
+    });
+    console.log(`Removed account '${name}'.`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.parseAsync();

package/docs/superpowers/plans/2026-03-22-cc-switch.md

@@ -0,0 +1,55 @@
+# cc-switch Implementation Plan
+
+> **Status: IMPLEMENTED** — All tasks completed.
+
+**Goal:** Build a Node.js CLI tool that manages Claude Code accounts. Each account is a directory with symlinks back to `~/.claude` (source of truth). Switching sets `CLAUDE_CONFIG_DIR` and launches `claude --continue`.
+
+**Architecture:** Single-binary CLI with Commander.js. Core logic: path constants, name validation, account population (symlinks back to `~/.claude`), account CRUD, and CLI entry point. All async with `fs/promises`. TDD with vitest.
+
+**Tech Stack:** Node.js 18+, TypeScript, Commander.js, vitest, tsup (bundler)
+
+**Spec:** `docs/superpowers/specs/2026-03-22-cc-switch-design.md`
+
+---
+
+## File Structure
+
+```
+src/
+├── cli.ts              # Commander.js setup, command definitions, launches claude --continue
+├── paths.ts            # Path constants with env var overrides for testing
+├── items.ts            # SWITCH_ITEMS list (12 items that get symlinked per-account)
+├── validate.ts         # Account name validation (sync - pure string logic)
+├── symlink.ts          # populateAccount (symlinks back to ~/.claude), readCurrent, writeCurrent
+├── accounts.ts         # listAccounts, addAccount, switchAccount, removeAccount, nextAccount
+└── index.ts            # Re-exports
+
+tests/
+├── validate.test.ts    # 6 tests
+├── symlink.test.ts     # 10 tests (populateAccount, readCurrent, writeCurrent)
+├── accounts.test.ts    # 15 tests (add, switch, remove, list, nextAccount)
+└── cli.test.ts         # 6 integration tests
+
+package.json
+tsconfig.json
+tsup.config.ts
+```
+
+## Key Design Decisions
+
+1. **`~/.claude` is NEVER modified** — it is the source of truth
+2. **Account dirs contain symlinks BACK to `~/.claude`** — not the other way around
+3. **Custom overrides** — user replaces a symlink in account dir with real file/dir; `populateAccount` skips existing items
+4. **`CLAUDE_CONFIG_DIR` env var** — used to tell Claude Code to read config from account dir
+5. **`claude --continue`** — always resumes previous session when launching
+6. **Single account = launch directly** — `cc-switch` with 1 account just launches it, no error
+
+## Tasks (all completed)
+
+- [x] Task 1: Project scaffolding (package.json, tsconfig, tsup, .gitignore)
+- [x] Task 2: Path constants with env var overrides
+- [x] Task 3: Account name validation + tests
+- [x] Task 4: Symlink operations (populateAccount, readCurrent, writeCurrent) + tests
+- [x] Task 5: Account CRUD operations + tests
+- [x] Task 6: CLI entry point with all commands + integration tests
+- [x] Task 7: Build, exports, link

package/docs/superpowers/specs/2026-03-22-cc-switch-design.md

@@ -0,0 +1,117 @@
+# cc-switch - Claude Code Account Switcher
+
+## Overview
+
+CLI tool (Node.js/TypeScript) to switch between multiple Claude Code accounts. Each account is a directory containing symlinks back to `~/.claude` (shared config) or custom override files. `~/.claude` is the source of truth and is **never modified** by cc-switch.
+
+When launching Claude Code, the tool sets `CLAUDE_CONFIG_DIR` to the account directory, so Claude reads config from there.
+
+## Core Principle
+
+```
+~/.claude/                              # SOURCE OF TRUTH — never modified
+├── settings.json                       # real file
+├── hooks/                              # real dir
+├── plugins/                            # real dir
+└── ...
+
+~/.cc-switch/
+├── .current                            # active account name
+└── claude-accounts/
+    ├── work/
+    │   ├── settings.json → ~/.claude/settings.json    # symlink (shared)
+    │   ├── hooks → ~/.claude/hooks                    # symlink (shared)
+    │   └── plugins/                                   # REAL dir (custom override)
+    └── personal/
+        ├── settings.json                              # REAL file (custom override)
+        ├── hooks → ~/.claude/hooks                    # symlink (shared)
+        └── ...
+```
+
+**Shared items** = symlinks back to `~/.claude` (default when adding account)
+**Custom overrides** = replace the symlink with a real file/dir in the account folder
+
+## Switchable Items
+
+The following items inside `~/.claude` are symlinked per-account:
+
+- `agents/`, `commands/`, `file-history/`, `hooks/`, `plugins/`
+- `projects/`, `rules/`, `session-env/`, `sessions/`
+- `settings.json`, `skills/`, `tasks/`
+
+## CLI Commands
+
+### `cc-switch` (no arguments)
+
+Auto switch to the next account (round-robin) and launch Claude Code.
+
+1. Read `.current` to get active account name
+2. List folders in `claude-accounts/`, sorted alphabetically (case-insensitive)
+3. If only 1 account → use that account directly
+4. If 2+ accounts → switch to the next one (wrap to first at end), update `.current`
+5. Launch `claude --continue` with `CLAUDE_CONFIG_DIR` set to the account directory
+
+### `cc-switch add <name>`
+
+Create a new account populated with symlinks back to `~/.claude`.
+
+1. Validate name (alphanumeric, hyphens, underscores; max 50 chars; no `.` or `-` prefix)
+2. Create `~/.cc-switch/claude-accounts/<name>/`
+3. For each switchable item that exists in `~/.claude`: create symlink `<name>/<item>` → `~/.claude/<item>`
+4. If this is the first account, set it as `.current`
+5. `~/.claude` is NOT modified
+
+### `cc-switch switch <name>`
+
+Switch to a specific account and launch Claude Code.
+
+1. Validate `<name>` exists in `claude-accounts/`
+2. If already active → print message and exit
+3. Update `.current`
+4. Launch `claude --continue` with `CLAUDE_CONFIG_DIR=<account-dir>`
+
+### `cc-switch list`
+
+List all accounts, marking the active one.
+
+```
+  work
+* personal (active)
+```
+
+### `cc-switch remove <name>`
+
+Remove an account.
+
+1. Prevent removing the currently active account
+2. Prevent removing the last remaining account
+3. Confirm with user (prompt y/n), support `--force` flag to skip
+4. Remove `~/.cc-switch/claude-accounts/<name>/`
+
+## How It Works
+
+- **Adding**: `cc-switch add work` creates `~/.cc-switch/claude-accounts/work/` with symlinks pointing back to `~/.claude/` for each switchable item
+- **Switching**: `cc-switch switch work` updates `.current` and runs `claude --continue` with `CLAUDE_CONFIG_DIR=~/.cc-switch/claude-accounts/work`
+- **Custom overrides**: User can replace any symlink in the account folder with a real file/dir. `cc-switch` will not overwrite existing items when populating.
+- **`~/.claude` is sacred**: cc-switch never reads from, writes to, or modifies `~/.claude` contents. It only reads to create initial symlinks during `add`.
+
+## Safety Checks
+
+- **`~/.claude` is never modified** — only used as symlink target
+- **Validate account names**: alphanumeric, hyphens, underscores only. Max 50 chars. Cannot start with `.` or `-`
+- **Preserve custom overrides**: `populateAccount` skips items that already exist in account dir
+- **Permissions**: create `~/.cc-switch/` with mode `700`
+
+## Tech Stack
+
+- Node.js + TypeScript
+- Commander.js for CLI parsing
+- Native `fs/promises` for async filesystem operations
+- `CLAUDE_CONFIG_DIR` env var to direct Claude Code to account folder
+- No heavy dependencies
+
+## Package
+
+- Name: `cc-switch`
+- Binary: `cc-switch`
+- Install: `npm install -g cc-switch`

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "cc-swap",
+  "version": "0.1.0",
+  "description": "Switch between multiple Claude Code accounts using symlinks",
+  "type": "module",
+  "bin": {
+    "cc-swap": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "account-switcher"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,105 @@
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import { validateName } from "./validate.js";
+import { populateAccount, readCurrent, writeCurrent } from "./symlink.js";
+
+interface AccountPaths {
+  claudeDir: string;
+  ccSwitchDir?: string;
+  accountsDir: string;
+  currentFile: string;
+  syncItems?: string[];
+}
+
+export async function listAccounts(accountsDir: string): Promise<string[]> {
+  try {
+    const entries = await fsPromises.readdir(accountsDir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
+  } catch {
+    return [];
+  }
+}
+
+export function nextAccount(current: string, accounts: string[]): string | null {
+  if (accounts.length <= 1) return null;
+  const idx = accounts.indexOf(current);
+  return accounts[(idx + 1) % accounts.length];
+}
+
+export async function addAccount(name: string, paths: AccountPaths): Promise<void> {
+  const { claudeDir, ccSwitchDir, accountsDir, currentFile } = paths;
+
+  const nameErr = validateName(name);
+  if (nameErr) throw new Error(nameErr);
+
+  const accountsExist = await fsPromises.access(accountsDir).then(() => true).catch(() => false);
+
+  if (!accountsExist) {
+    await fsPromises.mkdir(accountsDir, { recursive: true, mode: 0o700 });
+    if (ccSwitchDir) {
+      await fsPromises.chmod(ccSwitchDir, 0o700);
+    }
+  }
+
+  const target = path.join(accountsDir, name);
+  const exists = await fsPromises.access(target).then(() => true).catch(() => false);
+  if (exists) throw new Error(`Account '${name}' already exists`);
+
+  // Create account dir with symlinks pointing back to ~/.claude
+  await populateAccount(claudeDir, target, paths.syncItems ?? []);
+
+  // Set as current if this is the first account
+  const current = await readCurrent(currentFile);
+  if (!current) {
+    await writeCurrent(currentFile, name);
+  }
+}
+
+export async function switchAccount(
+  name: string,
+  paths: Pick<AccountPaths, "claudeDir" | "accountsDir" | "currentFile">
+): Promise<string> {
+  const nameErr = validateName(name);
+  if (nameErr) throw new Error(nameErr);
+
+  const { accountsDir, currentFile } = paths;
+  const target = path.join(accountsDir, name);
+
+  const exists = await fsPromises.access(target).then(() => true).catch(() => false);
+  if (!exists) throw new Error(`Account '${name}' does not exist`);
+
+  const current = await readCurrent(currentFile);
+  if (current === name) return `'${name}' is already active`;
+
+  await writeCurrent(currentFile, name);
+  return `Switched to: ${name}`;
+}
+
+export async function removeAccount(
+  name: string,
+  paths: Pick<AccountPaths, "accountsDir" | "currentFile">
+): Promise<void> {
+  const nameErr = validateName(name);
+  if (nameErr) throw new Error(nameErr);
+
+  const { accountsDir, currentFile } = paths;
+  const target = path.join(accountsDir, name);
+
+  const exists = await fsPromises.access(target).then(() => true).catch(() => false);
+  if (!exists) throw new Error(`Account '${name}' does not exist`);
+
+  const current = await readCurrent(currentFile);
+  if (current === name) {
+    throw new Error(`Cannot remove '${name}' — it is currently active. Switch to another account first.`);
+  }
+
+  const all = await listAccounts(accountsDir);
+  if (all.length <= 1) {
+    throw new Error(`Cannot remove '${name}' — it is the last remaining account.`);
+  }
+
+  await fsPromises.rm(target, { recursive: true, force: true });
+}