claude-switch-profile 1.1.0 → 1.4.2

package/.cocoindex_code/settings.yml

@@ -0,0 +1,41 @@
+exclude_patterns:
+- '**/.*'
+- '**/__pycache__'
+- '**/node_modules'
+- '**/target'
+- '**/build/assets'
+- '**/dist'
+- '**/vendor/*.*/*'
+- '**/vendor/*'
+- '**/.cocoindex_code'
+include_patterns:
+- '**/*.py'
+- '**/*.pyi'
+- '**/*.js'
+- '**/*.jsx'
+- '**/*.ts'
+- '**/*.tsx'
+- '**/*.mjs'
+- '**/*.cjs'
+- '**/*.rs'
+- '**/*.go'
+- '**/*.java'
+- '**/*.c'
+- '**/*.h'
+- '**/*.cpp'
+- '**/*.hpp'
+- '**/*.cc'
+- '**/*.cxx'
+- '**/*.hxx'
+- '**/*.hh'
+- '**/*.cs'
+- '**/*.sql'
+- '**/*.sh'
+- '**/*.bash'
+- '**/*.zsh'
+- '**/*.md'
+- '**/*.mdx'
+- '**/*.txt'
+- '**/*.rst'
+- '**/*.php'
+- '**/*.lua'

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to `claude-switch-profile` are documented here.
 
+## [Unreleased]
+
+### Changed
+- _No changes yet._
+
+---
+
+## [1.4.1] - 2026-03-31
+
+### Changed
+- `default` is now a physical profile snapshot created by `csp init` instead of a virtual pass-through.
+- `csp save`, `csp use`, `csp export`, `csp launch`, and `csp uninstall` now operate on the `default` snapshot the same way they do for other profiles.
+- Legacy installs missing `~/.claude-profiles/default` only backfill that snapshot when the active profile is `default` or no active profile is set; if a non-default profile is active, CSP fails closed with repair guidance.
+- Protected and session/runtime files remain excluded from snapshot capture, export, isolated runtime sync, and restore flows.
+- Launching `default` keeps its metadata mode as `legacy` instead of drifting to `account-session`.
+- README command reference refreshed to match current CLI behavior (`select` default command, `status`, `toggle`, `create --source`, import symlink safety validation, updated project structure, and GitHub repository link).
+
+---
+
+## [1.3.0] - 2026-03-28
+
+### Added
+- ✨ **Interactive profile selector** — Run `csp` with no arguments to get an arrow-key profile picker that launches isolated sessions. Supports ↑/↓/j/k navigation, Enter to select, Esc to cancel.
+- ✨ **`csp status`** — Dashboard showing active profile, profile count, last launch info, and Claude running status at a glance.
+- ✨ **`csp toggle`** — Quick-switch to the previous profile (like `cd -`). Uses isolated launch, never touches ~/.claude.
+- ✨ **`csp select`** — Explicit alias for the interactive selector.
+
+### Changed
+- 🔒 **`~/.claude` is never modified** — All profile operations now use isolated runtime (`CLAUDE_CONFIG_DIR`). The `default` profile is a virtual alias for `~/.claude` as-is.
+- 🔒 **`default` profile is virtual** — `csp init` no longer creates a physical directory for the default profile. Default means "use ~/.claude directly".
+- 🔒 **`csp launch default`** — Launches Claude with native `~/.claude` (no runtime dir, no `CLAUDE_CONFIG_DIR` override).
+- 🔒 **`csp deactivate`** — Now simply resets active marker to `default`. No longer deletes files from `~/.claude`.
+- ⚠️ **`csp use` deprecated** — Shows warning that it modifies `~/.claude` (legacy mode). Users should prefer `csp launch`.
+- 🔄 **`csp toggle`** — Now uses `launch` (isolated) instead of `use` (legacy).
+
+### Fixed
+- 🐛 Removed dead `--force` option from `csp use`.
+- 🐛 Fixed double `getActive()` call in `init` command.
+- 🐛 Fixed stale "symlink targets" comment in safety.js.
+- 🐛 Removed unused parameter in diff.js.
+
+---
+
 ## [1.1.0] - 2026-03-13
 
 ### Added

package/README.md

@@ -4,7 +4,9 @@
 [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-A CLI tool for managing multiple Claude Code configurations and profiles. Effortlessly switch between different development setups, each with their own rules, agents, skills, and settings.
+**GitHub:** https://github.com/ThanhThi2895/claude-switch-profile
+
+A CLI tool for managing multiple Claude Code configurations and profiles. Use legacy global switching (`csp use`) or concurrent isolated account sessions (`csp launch`) with per-profile runtime roots.
 
 ## Overview
 
@@ -46,19 +48,20 @@ csp --help
 ### Requirements
 
 - Node.js >= 18.0.0
-- Unix/Linux/macOS (uses symlinks and POSIX tools)
+- Unix/Linux/macOS
+- Windows 10+
 
 ## Quick Start
 
 ### 1. Initialize
 
-Capture your current Claude Code setup as the default profile:
+Capture your current Claude Code setup as the physical `default` profile snapshot:
 
 ```bash
 csp init
 ```
 
-This creates `~/.claude-profiles/default/` containing your current configuration.
+This creates `~/.claude-profiles/default/` from the current managed contents of `~/.claude`. Protected and session/runtime files remain excluded.
 
 ### 2. Create Additional Profiles
 
@@ -115,7 +118,15 @@ Output example:
 
 The `*` marks the active profile.
 
-### 6. Uninstall CSP
+### 6. Launch via Interactive Selector (Default Command)
+
+Run `csp` without a subcommand to open the interactive selector and launch a profile immediately:
+
+```bash
+csp
+```
+
+### 7. Uninstall CSP
 
 Remove CSP and restore your Claude Code to its original state:
 
@@ -126,6 +137,22 @@ csp uninstall
 
 ## Commands Reference
 
+### select (default)
+
+Open interactive profile selector (default behavior when you run `csp` without subcommand).
+
+```bash
+csp
+csp select
+```
+
+**Behavior:**
+- If TTY and multiple profiles exist: shows arrow-key menu and launches selected profile via `csp launch <name>`
+- If only one profile exists: shows informational message and exits
+- If non-interactive terminal: asks to use `csp launch <name>` or `csp use <name>` directly
+
+---
+
 ### init
 
 Initialize the profile system and capture current state as "default" profile.
@@ -146,7 +173,7 @@ csp init
 
 ### current
 
-Display the currently active profile.
+Display the currently active **legacy** profile and isolated launch metadata (if present).
 
 ```bash
 csp current
@@ -154,8 +181,10 @@ csp current
 
 **Output:**
 ```
-✓ Active profile: default
+✓ Active legacy profile: default
 ℹ Location: /home/user/.claude-profiles/default
+ℹ Last isolated launch: 2026-03-26T14:45:00.000Z
+ℹ Isolated runtime: /home/user/.claude-profiles/.runtime/default
 ```
 
 ---
@@ -171,14 +200,24 @@ csp ls
 
 **Output format:**
 ```
- * profile-name — optional description (YYYY-MM-DD)
-   other-profile (YYYY-MM-DD)
+ * profile-name — optional description (YYYY-MM-DD) [legacy|account-session]
+   other-profile (YYYY-MM-DD) [account-session]
 ```
 
 The `*` marks the currently active profile.
 
 ---
 
+### status
+
+Show CSP status dashboard (active profile, profile count, last launch, Claude process state).
+
+```bash
+csp status
+```
+
+---
+
 ### create
 
 Create a new profile from current state or clone existing profile.
@@ -189,6 +228,7 @@ csp create <name> [options]
 
 **Options:**
 - `--from <profile>` — Clone from existing profile instead of current state
+- `-s, --source <path>` — Create from a specific kit directory, then inherit missing managed items from current `~/.claude`
 - `-d, --description <text>` — Add description to profile
 
 **Examples:**
@@ -208,10 +248,16 @@ Clone from existing:
 csp create backup --from production
 ```
 
+Create from kit directory:
+```bash
+csp create team-kit --source ~/my-kit/.agents -d "Team baseline"
+```
+
 **Behavior:**
 - Creates profile directory: `~/.claude-profiles/<name>/`
 - If `--from` is specified, clones all content from source profile
-- Otherwise, captures current `~/.claude` state
+- If `--source` is specified, copies managed items from that directory, then fills missing managed items from current `~/.claude`
+- Otherwise, performs full clone of current `~/.claude` excluding protected/session items
 - If this is the first profile, automatically sets it as active
 - Saves metadata (created timestamp, description)
 
@@ -226,10 +272,11 @@ csp save
 ```
 
 **Behavior:**
-- Captures all managed symlinks and files from `~/.claude`
-- Overwrites profile's `source.json` and file copies
-- Useful after modifying rules, settings, or other configuration
-- Requires active profile (run `csp create` if none exists)
+- Captures all managed items and copied files/directories from `~/.claude`
+- Overwrites the active profile snapshot (`source.json` plus copied content)
+- When `default` is active, updates the physical `default` snapshot like any other profile
+- Protected and session/runtime files remain excluded
+- Requires an active profile
 
 ---
 
@@ -244,7 +291,6 @@ csp use <name> [options]
 **Options:**
 - `--dry-run` — Show what would change without executing
 - `--no-save` — Skip saving current profile before switching
-- `--force` — Switch even if some symlink targets are missing
 
 **Examples:**
 
@@ -263,20 +309,30 @@ Switch without saving current state:
 csp use backup --no-save
 ```
 
-Force switch with missing targets:
+**Behavior:**
+1. Validates target profile exists and profile structure is valid
+2. Refuses to switch while Claude Code is running (legacy/global switching mutates `~/.claude` directly)
+3. If the active profile exists and `--no-save` is not set: saves its current snapshot first
+4. Removes managed items/files from `~/.claude`
+5. Restores the target profile snapshot into `~/.claude` — including `default`
+6. Updates active marker
+7. On older installs missing `profiles/default`, CSP only backfills that snapshot when the active profile is `default` or no active profile is set; otherwise it fails closed with repair guidance
+8. **Important:** Claude Code session must be restarted for changes to apply
+
+---
+
+### toggle
+
+Launch the previous profile (does not mutate global active profile in isolated mode).
+
 ```bash
-csp use legacy --force
+csp toggle
 ```
 
 **Behavior:**
-1. Validates target profile exists and is valid
-2. (Optional) Validates symlink targets exist
-3. If active profile exists and `--no-save` is not set: saves current state
-4. Creates automatic backup at `~/.claude-profiles/.backup/`
-5. Removes all managed items from `~/.claude`
-6. Restores target profile's symlinks and files
-7. Updates active marker
-8. **Important:** Claude Code session must be restarted for changes to apply
+- Reads previous profile marker from `~/.claude-profiles/.previous`
+- Validates previous profile still exists
+- Delegates to `csp launch <previous>`
 
 ---
 
@@ -306,10 +362,11 @@ csp delete old-setup --force
 ```
 
 **Behavior:**
-- Cannot delete the active profile (must switch first)
+- Cannot delete `default`
 - Prompts for confirmation unless `--force` is used
 - Permanently removes profile directory and metadata
-- Cannot be undone (but auto-backups from `use` are preserved)
+- If deleting the currently active non-default profile: clears active marker only (does not mutate `~/.claude`)
+- Cannot be undone
 
 ---
 
@@ -338,8 +395,10 @@ csp export staging -o ~/backups/claude-staging.tar.gz
 ```
 
 **Behavior:**
-- Creates tar.gz archive of entire profile directory
-- Includes source.json (symlink targets) and all copied files
+- Creates tar.gz archive of the profile snapshot directory
+- Includes `source.json` plus copied profile files/directories
+- Exporting `default` works like any other profile snapshot
+- Protected and session/runtime files remain excluded from the archive
 - Useful for backup, sharing, or version control
 
 ---
@@ -372,6 +431,8 @@ csp import backup.tar.gz -n restored -d "Restored from backup"
 **Behavior:**
 - Extracts archive to `~/.claude-profiles/<name>/`
 - Uses filename as profile name if `--name` not specified
+- Validates imported profile structure
+- Rejects import if managed/copied items contain symlink targets outside profile directory (safety check)
 - Creates metadata entry for profile
 - Profile is ready to use immediately
 
@@ -403,7 +464,7 @@ csp diff current backup
 ```
 Comparing: staging ↔ production
 
-Symlink targets (source.json): identical
+Managed item map (source.json): identical
 
 File differences:
   settings.json — different
@@ -412,10 +473,83 @@ File differences:
 ```
 
 **Behavior:**
-- Compares `source.json` (symlink targets)
+- Compares `source.json` (managed item map)
 - Lists file presence and content differences
 - Shows which files differ and in which profile they exist
 
+---
+
+### deactivate
+
+Deactivate the currently active non-default profile by switching back to the physical `default` snapshot.
+
+```bash
+csp deactivate
+```
+
+**Options:**
+- `--no-save` — Skip saving current profile state before deactivation
+
+**Behavior:**
+1. Exits early if no active profile or active profile is `default`
+2. Delegates to `csp use default`
+3. Optionally saves the current non-default profile state
+4. Restores the physical `default` snapshot into `~/.claude`
+5. Marks `default` as the active legacy profile
+
+---
+
+### launch (la)
+
+Launch an isolated Claude session for a profile. This does **not** change global active profile. All extra arguments are forwarded to `claude`.
+
+```bash
+csp launch <name> [claude-args...]
+csp la <name> [claude-args...]
+```
+
+**Options:**
+- `--legacy-global` — Use old behavior (`csp use <name>` then launch)
+
+**Examples:**
+
+Launch isolated session:
+```bash
+csp launch work
+```
+
+Launch isolated with Claude flags:
+```bash
+csp launch work --dangerously-skip-permissions
+csp la dev --model opus
+```
+
+Launch legacy/global mode:
+```bash
+csp launch work --legacy-global
+```
+
+**Behavior (default isolated mode):**
+1. Validates target profile exists
+2. Ensures the profile snapshot exists; for legacy installs missing `default/`, guarded backfill only runs when the active profile is `default` or no active profile is set
+3. Prepares per-profile runtime under `~/.claude-profiles/.runtime/<name>`
+4. Resolves effective allowlisted `ANTHROPIC_*` launch env (`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`) with precedence: `settings.json env` > profile `.env` allowlist > parent process env
+5. Strips inherited `CLAUDECODE`, inherited `CLAUDE_CONFIG_DIR`, inherited `ANTHROPIC_*`, and Claude session env vars before applying resolved allowlisted values
+6. Spawns `claude` with `CLAUDE_CONFIG_DIR=<runtimeDir>`
+7. Inherits stdin/stdout/stderr for interactive use
+8. Forwards Claude's exit code
+9. Keeps `.active` unchanged and never mutates global `~/.claude`
+10. Launching `default` preserves its `legacy` mode metadata even though it uses an isolated runtime snapshot
+
+`ANTHROPIC_*` keys currently in isolated launch scope:
+- `ANTHROPIC_AUTH_TOKEN`
+- `ANTHROPIC_BASE_URL`
+- `ANTHROPIC_MODEL`
+
+Set `CSP_DEBUG_LAUNCH_ENV=1` to print extended launch diagnostics. Do not use in shared logs because it can include resolved `ANTHROPIC_*` values.
+
+---
+
 ### uninstall
 
 Remove all profiles and restore Claude Code to its pre-CSP state.
@@ -448,9 +582,10 @@ csp uninstall --force
 
 **Behavior:**
 1. Creates a final backup at `~/.claude-profiles/.backup/`
-2. Restores the active profile (or `--profile` choice) to `~/.claude`
-3. Removes `~/.claude-profiles/` entirely
-4. Prints reminder to run `npm uninstall -g claude-switch-profile`
+2. Restores the active profile by default, or the `--profile` choice, to `~/.claude`
+3. If `default` is restored, it uses the physical `default` snapshot like any other profile
+4. Removes `~/.claude-profiles/` entirely
+5. Prints reminder to run `npm uninstall -g claude-switch-profile`
 
 ---
 
@@ -462,10 +597,13 @@ Profiles are stored in `~/.claude-profiles/`:
 
 ```
 ~/.claude-profiles/
-├── .active                    # Current active profile name
-├── profiles.json              # Metadata for all profiles
+├── .active                    # Current active profile name (legacy use mode)
+├── profiles.json              # Metadata for all profiles (v2 schema)
+├── .runtime/                  # Isolated launch roots
+│   ├── work/
+│   └── personal/
 ├── default/
-│   ├── source.json           # Symlink targets
+│   ├── source.json           # Managed item map
 │   ├── settings.json         # Copied from ~/.claude
 │   ├── .env                  # Copied from ~/.claude
 │   ├── .ck.json              # Copied from ~/.claude
@@ -480,56 +618,60 @@ Profiles are stored in `~/.claude-profiles/`:
 
 ### What Gets Managed
 
-**Symlinked Items** (via `source.json`):
+**Managed Static Items** (via `source.json`):
 - `CLAUDE.md` — Project-specific Claude configuration
 - `rules/` — Development rules and guidelines
 - `agents/` — Agent scripts and configurations
 - `skills/` — Custom Luna skills
 - `hooks/` — Pre/post action hooks
-- `statusline.cjs` — Custom statusline
+- `statusline.cjs`, `statusline.sh`, `statusline.ps1` — Custom statusline scripts
 - `.luna.json` — Luna configuration
 
 **Copied Files**:
 - `settings.json` — Editor settings
-- `.env` — Environment variables
-- `.ck.json` — Custom settings
-- `.ckignore` — Ignore patterns
+- `.env`, `.env.example` — Environment variables
+- `.ck.json`, `.ckignore` — Custom settings and ignore patterns
+- `.mcp.json`, `.mcp.json.example` — MCP configuration
+- `.gitignore` — Local ignore settings
 
 **Copied Directories**:
-- `commands/` — Custom commands
-- `plugins/` — Custom plugins
+- `commands/`, `plugins/` — Custom commands/plugins
+- `workflows/`, `scripts/` — Automation and workflow assets
+- `output-styles/`, `schemas/` — Output and schema assets
 
 **Never Touched** (runtime/session data):
 - `.credentials.json`
-- `projects/`
-- `backups/`
-- `cache/`, `debug/`, `telemetry/`
-- `history.jsonl`
-- `plans/`, `todos/`, `tasks/`
-- `agent-memory/`, `session-env/`
-- All other session-specific data
+- `projects/`, `sessions/`, `session-env/`, `ide/`
+- `cache/`, `paste-cache/`, `downloads/`, `telemetry/`, `debug/`, `statsig/`
+- `history.jsonl`, `metadata.json`, `stats-cache.json`, `active-plan`
+- `backups/`, `command-archive/`, `commands-archived/`
+- `plans/`, `todos/`, `tasks/`, `teams/`, `agent-memory/`, `file-history/`, `shell-snapshots/`
+- All other protected or session-specific data
 
-### Symlink vs. Copy Strategy
+### Legacy vs Isolated Launch Modes
 
-**Why symlinks for some items?**
-- Rules, agents, skills often live in external git repos
-- Multiple profiles may share the same rules/skills
-- Symlinks avoid duplication and keep everything in sync
+CSP now supports two paths:
 
-**Why copies for others?**
-- Settings and env vars are environment-specific
-- Each profile needs its own independent configuration
-- Prevents accidental modifications from affecting other profiles
+- **Legacy global mode (`csp use`)**
+  - Mutates `~/.claude`
+  - Updates `.active`
+  - Preserves old behavior for existing scripts
 
-### Real Directory Handling
+- **Isolated launch mode (`csp launch`)**
+  - Does not mutate `~/.claude`
+  - Does not change `.active`
+  - Creates/updates runtime root per profile at `~/.claude-profiles/.runtime/<name>`
+  - Launches Claude with `CLAUDE_CONFIG_DIR` pointing to that runtime root
 
-When `csp save` (or `csp use`) encounters a **real directory/file** in `~/.claude` for a managed item (instead of a symlink), it automatically:
+### Runtime Sync Policy (isolated launch)
 
-1. **Moves** the real item into the profile directory (`~/.claude-profiles/<name>/<item>`)
-2. **Replaces** it with a symlink at the original location
-3. **Records** the new location in `source.json`
+For each launch, CSP syncs static profile config into runtime root:
 
-This ensures that profiles created from a fresh `~/.claude` setup (before any symlinks exist) work correctly on first use.
+- Managed items (`CLAUDE.md`, `rules`, `agents`, `skills`, `hooks`, statusline files, `.luna.json`)
+- Copied files (`settings.json`, `.env`, `.ck.json`, `.ckignore`, etc.)
+- Copied directories (`commands`, `plugins`, `workflows`, `scripts`, ...)
+
+Runtime/account continuity stays isolated per runtime root and is not globally swapped.
 
 ## Safety Features
 
@@ -561,7 +703,7 @@ Every profile switch creates a timestamped backup:
     └── ...
 ```
 
-Backups are kept indefinitely. You can manually restore by copying from backup directory.
+Backups are pruned automatically; CSP keeps only the 2 most recent backups. You can manually restore by copying from backup directory.
 
 ### Claude Process Detection
 
@@ -573,18 +715,19 @@ When switching profiles, CSP detects if Claude Code is running:
 
 **Important:** Changes only take effect after restarting Claude Code.
 
+### Windows Support
+
+Process detection uses `tasklist` instead of `pgrep` on Windows.
+
+Export/import commands use the built-in `tar.exe` available on Windows 10+.
+
 ### Validation
 
 Before switching, CSP validates:
 1. Target profile exists
 2. Profile structure is valid
-3. (Optional with `--force`) Symlink targets are accessible
-
-Use `--force` to proceed even if validation fails:
 
-```bash
-csp use legacy --force
-```
+During import, CSP also validates profile contents and rejects unsafe symlinks that point outside the imported profile tree.
 
 ## Configuration via Environment Variables
 
@@ -643,7 +786,7 @@ csp use personal  # Switch to personal
 
 ```bash
 # Clone current profile
-csp create experimental --from current -d "Testing new Luna skills"
+csp create experimental --from default -d "Testing new Luna skills"
 
 # Switch and experiment
 csp use experimental
@@ -707,15 +850,14 @@ csp list
 csp use production  # if "production" exists
 ```
 
-### Cannot delete active profile
+### Cannot delete default profile
 
-**Error:** `Cannot delete active profile "default". Switch to another profile first.`
+**Error:** `Cannot delete the default profile.`
 
-**Solution:** Switch to a different profile before deleting.
+**Solution:** Keep `default` and delete only non-default profiles.
 
 ```bash
-csp use production
-csp delete default
+csp delete experimental
 ```
 
 ### Stale lock file
@@ -728,15 +870,11 @@ csp delete default
 rm ~/.claude-profiles/.lock
 ```
 
-### Symlink targets missing
-
-**Warning:** `Some symlink targets are missing: rules/development-rules.md — missing target`
+### Invalid profile structure
 
-**Solution:** Either restore the missing files to their original location or use `--force`:
+**Error:** `Profile "name" is invalid: Missing source.json — no managed items defined`
 
-```bash
-csp use production --force
-```
+**Solution:** Recreate the profile or import a valid profile archive.
 
 ### Changes not applying
 
@@ -775,17 +913,26 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and migration guidance.
 │   │   ├── init.js
 │   │   ├── current.js
 │   │   ├── list.js
+│   │   ├── status.js
 │   │   ├── create.js
 │   │   ├── save.js
 │   │   ├── use.js
+│   │   ├── toggle.js
 │   │   ├── delete.js
 │   │   ├── export.js
 │   │   ├── import.js
-│   │   └── diff.js
+│   │   ├── diff.js
+│   │   ├── select.js
+│   │   ├── launch.js
+│   │   ├── deactivate.js
+│   │   └── uninstall.js
 │   ├── constants.js              # Configuration constants
+│   ├── platform.js               # Cross-platform compatibility
 │   ├── profile-store.js          # Profile metadata management
-│   ├── symlink-manager.js        # Symlink operations
+│   ├── runtime-instance-manager.js # Isolated runtime sync
+│   ├── item-manager.js           # Managed item copy/move operations
 │   ├── file-operations.js        # File copy/restore operations
+│   ├── launch-effective-env-resolver.js # ANTHROPIC_* launch env resolution
 │   ├── safety.js                 # Locking, backups, validation
 │   ├── profile-validator.js      # Profile validation
 │   └── output-helpers.js         # Console output formatting