claude-switch-profile 1.4.8 → 1.4.12

package/CHANGELOG.md

@@ -9,6 +9,76 @@ All notable changes to `claude-switch-profile` are documented here.
 
 ---
 
+## [1.4.11] - 2026-04-01
+
+### Changed
+- Version bump only — no functional code changes from `1.4.10`.
+
+---
+
+## [1.4.10] - 2026-04-01
+
+### Fixed
+- **Settings Path Mutation Bug**: Fixed a severe issue where hook paths in `settings.json` could exponentially multiply (like `.runtime/default-profiles/.runtime/...`) when saving a profile post-launch. Path mapping logic was strengthened to use exact-boundary Regular Expressions, preventing `.claude` patterns from incorrectly matching adjacent nested paths like `.claude-profiles`.
+
+---
+
+## [1.4.9] - 2026-04-01
+
+### Fixed
+- **Hooks execution in isolated mode**: Fixed an issue where Claude Code hook scripts failed to execute in isolated profiles. The runtime instance manager now correctly resolves shell variables (`$HOME`, `${HOME}`, `~`) within `settings.json` hook commands to accurately point to the isolated runtime directory.
+
+---
+
+## [1.4.8] - 2026-04-01
+
+### Changed
+- Re-ran release flow to publish the latest patch after `1.4.7`.
+- No functional code changes compared with `1.4.7`; this release aligns npm package/version metadata.
+
+---
+
+## [1.4.7] - 2026-04-01
+
+### Fixed
+- Release pipeline now restores annotated git tag publishing.
+- Local agent artifacts are ignored by git to keep release working tree clean.
+
+---
+
+## [1.4.6] - 2026-03-31
+
+### Fixed
+- Excluded cocoindex cache from npm package to reduce published size.
+
+---
+
+## [1.4.5] - 2026-03-31
+
+### Fixed
+- Release pipeline: stopped creating duplicate git tags during release.
+
+---
+
+## [1.4.4] - 2026-03-31
+
+### Fixed
+- Release pipeline: handled noisy test output that could interrupt release flow.
+
+---
+
+## [1.4.3] - 2026-03-31
+
+### Added
+- ✨ **`csp exec` command** — Run an arbitrary command inside an isolated profile runtime environment. Similar to `csp launch` but runs any command (not just Claude) under profile-scoped env. Supports `--` separator for command arguments.
+- ✨ **Dynamic shell support for `csp exec`** — On Unix-like systems, commands run through the user's interactive shell so shell aliases and functions resolve naturally while keeping runtime isolation intact.
+
+### Changed
+- Refactored `launch.js` to share context setup with `exec` via `isolated-launch-context.js`.
+- On Windows, `exec` falls back to direct spawn with `.cmd` / `.bat` wrapper detection.
+
+---
+
 ## [1.4.2] - 2026-03-31
 
 ### Changed

package/README.md

@@ -20,618 +20,87 @@ Profiles are stored in `~/.claude-profiles/` and are never managed by Claude Cod
 
 ## Installation
 
-### Global Installation
-
 ```bash
 npm install -g claude-switch-profile
 ```
 
-Then use the `csp` command globally:
-
-```bash
-csp list
-csp current
-csp create my-profile
-```
-
-### Local Development
-
-```bash
-# In the project root
-npm install
-npm link
-
-# Now available as `csp` command
-csp --help
-```
-
-### Requirements
-
-- Node.js >= 18.0.0
-- Unix/Linux/macOS
-- Windows 10+
+**Requirements:** Node.js >= 18.0.0 | macOS/Linux/Windows 10+
 
 ## Quick Start
 
-### 1. Initialize
-
-Capture your current Claude Code setup as the physical `default` profile snapshot:
-
 ```bash
+# 1. Initialize — capture current setup as "default" profile
 csp init
-```
-
-This creates `~/.claude-profiles/default/` from the current managed contents of `~/.claude`. Protected and session/runtime files remain excluded.
-
-### 2. Create Additional Profiles
-
-Create a new profile from your current state:
-
-```bash
-csp create work --description "Work setup with company rules"
-```
-
-Or clone from an existing profile:
-
-```bash
-csp create experimental --from default --description "Testing new tools"
-```
-
-### 3. Switch Between Profiles
-
-Switch to a profile (automatically saves current state):
-
-```bash
-csp use work
-# Restart your Claude Code session for changes to take effect
-```
-
-Use `--dry-run` to preview changes:
-
-```bash
-csp use work --dry-run
-```
-
-### 4. Save Current State
-
-Save the active profile with current configuration:
-
-```bash
-csp save
-```
-
-### 5. List All Profiles
-
-View all available profiles with their status:
-
-```bash
-csp list
-```
-
-Output example:
 
-```
- * default — Vanilla Claude defaults (2026-03-11)
-   work — Work setup (2026-03-11)
-   experimental (2026-03-11)
-```
-
-The `*` marks the active profile.
-
-### 6. Launch via Interactive Selector (Default Command)
-
-Run `csp` without a subcommand to open the interactive selector and launch a profile immediately:
-
-```bash
-csp
-```
+# 2. Create additional profiles
+csp create work -d "Work setup with company rules"
+csp create experimental --from default -d "Testing new tools"
 
-### 7. Uninstall CSP
-
-Remove CSP and restore your Claude Code to its original state:
-
-```bash
-csp uninstall
-# Uninstall CSP and remove all profiles? This cannot be undone. (y/N)
-```
-
-## Commands Reference
-
-### select (default)
-
-Open interactive profile selector (default behavior when you run `csp` without subcommand).
+# 3. Launch isolated sessions (recommended — does NOT touch ~/.claude)
+csp launch work
+csp launch experimental
 
-```bash
+# 4. Or use the interactive selector
 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.
-
-```bash
-csp init
-```
-
-**Options:** None
-
-**Behavior:**
-- Creates `~/.claude-profiles/` directory
-- Captures current `~/.claude` configuration
-- Creates `default` profile and marks it active
-- If already initialized, displays current active profile
-
----
-
-### current
-
-Display the currently active **legacy** profile and isolated launch metadata (if present).
-
-```bash
-csp current
-```
-
-**Output:**
-```
-✓ 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
-```
-
----
-
-### list (ls)
-
-List all profiles with descriptions and creation dates.
-
-```bash
-csp list
-csp ls
-```
-
-**Output format:**
-```
- * 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.
-
-```bash
-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:**
-
-Create from current state:
-```bash
-csp create production
-```
-
-Create with description:
-```bash
-csp create staging -d "Staging environment with logging enabled"
-```
-
-Clone from existing:
-```bash
-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
-- 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)
-
----
-
-### save
-
-Save the current `~/.claude` state to the active profile.
-
-```bash
-csp save
-```
-
-**Behavior:**
-- 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
-
----
-
-### use
-
-Switch to a different profile.
-
-```bash
-csp use <name> [options]
-```
-
-**Options:**
-- `--dry-run` — Show what would change without executing
-- `--no-save` — Skip saving current profile before switching
-
-**Examples:**
-
-Simple switch:
-```bash
-csp use production
-```
-
-Preview changes first:
-```bash
-csp use staging --dry-run
-```
-
-Switch without saving current state:
-```bash
-csp use backup --no-save
-```
-
-**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 toggle
-```
-
-**Behavior:**
-- Reads previous profile marker from `~/.claude-profiles/.previous`
-- Validates previous profile still exists
-- Delegates to `csp launch <previous>`
-
----
-
-### delete (rm)
-
-Delete a profile.
-
-```bash
-csp delete <name> [options]
-csp rm <name> [options]
-```
-
-**Options:**
-- `-f, --force` — Skip confirmation prompt
-
-**Examples:**
-
-Delete with confirmation:
-```bash
-csp delete experimental
-# Delete profile "experimental"? This cannot be undone. (y/N)
-```
-
-Force delete without prompt:
-```bash
-csp delete old-setup --force
-```
-
-**Behavior:**
-- Cannot delete `default`
-- Prompts for confirmation unless `--force` is used
-- Permanently removes profile directory and metadata
-- If deleting the currently active non-default profile: clears active marker only (does not mutate `~/.claude`)
-- Cannot be undone
-
----
-
-### export
-
-Export a profile as a compressed tar.gz archive.
-
-```bash
-csp export <name> [options]
-```
-
-**Options:**
-- `-o, --output <path>` — Output file path (defaults to `./{name}.csp.tar.gz`)
-
-**Examples:**
-
-Export with default filename:
-```bash
-csp export production
-# Exports to ./production.csp.tar.gz
-```
-
-Export to custom location:
-```bash
-csp export staging -o ~/backups/claude-staging.tar.gz
-```
-
-**Behavior:**
-- 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
-
----
-
-### import
-
-Import a profile from tar.gz archive.
-
-```bash
-csp import <file> [options]
-```
-
-**Options:**
-- `-n, --name <name>` — Profile name (defaults to archive filename without extension)
-- `-d, --description <text>` — Profile description
-
-**Examples:**
-
-Import with default name:
-```bash
-csp import production.csp.tar.gz
-# Creates profile named "production"
-```
-
-Import with custom name and description:
-```bash
-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
-
----
-
-### diff
-
-Compare two profiles to identify differences.
-
-```bash
-csp diff <profileA> <profileB>
 ```
 
-**Special:** Use `current` to compare against active profile.
-
-**Examples:**
-
-Compare two profiles:
-```bash
-csp diff staging production
-```
-
-Compare current profile with another:
-```bash
-csp diff current backup
-```
-
-**Output:**
-```
-Comparing: staging ↔ production
-
-Managed item map (source.json): identical
-
-File differences:
-  settings.json — different
-  .env — only in production
-  rules/CLAUDE.md — different
-```
-
-**Behavior:**
-- 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
-
----
+## Core Commands
 
-### launch (la)
+| Command | Description |
+|---|---|
+| `csp` / `csp select` | Interactive profile selector (default) |
+| `csp init` | Initialize and capture current state as `default` profile |
+| `csp create <name>` | Create a new profile (`--from`, `--source`, `-d` options) |
+| `csp launch <name>` | Launch isolated Claude session for a profile |
+| `csp exec <name> -- <cmd>` | Run any command inside isolated profile runtime |
+| `csp use <name>` | Legacy global switch (mutates `~/.claude`) |
+| `csp save` | Save current state to active profile |
+| `csp list` / `csp ls` | List all profiles |
+| `csp status` | Show CSP status dashboard |
+| `csp current` | Show active legacy profile |
+| `csp toggle` | Quick-switch to previous profile |
+| `csp diff <a> <b>` | Compare two profiles |
+| `csp export <name>` | Export profile as `.tar.gz` archive |
+| `csp import <file>` | Import profile from archive |
+| `csp delete <name>` | Delete a profile |
+| `csp deactivate` | Switch back to `default` profile |
+| `csp uninstall` | Remove CSP and restore Claude to pre-CSP state |
 
-Launch an isolated Claude session for a profile. This does **not** change global active profile. All extra arguments are forwarded to `claude`.
+> 📖 **Full command reference with all options and detailed behavior:** [docs/commands-reference.md](docs/commands-reference.md)
 
-```bash
-csp launch <name> [claude-args...]
-csp la <name> [claude-args...]
-```
-
-**Options:**
-- `--legacy-global` — Use old behavior (`csp use <name>` then launch)
+## Two Launch Modes
 
-**Examples:**
+### Isolated Launch (recommended)
 
-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.
-
----
+- Does **not** mutate `~/.claude` or change `.active`
+- Creates per-profile runtime at `~/.claude-profiles/.runtime/<name>`
+- Spawns Claude with `CLAUDE_CONFIG_DIR` pointing to runtime root
+- Supports `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` env resolution
 
-### exec
+### Legacy Global Switch
 
-Run an arbitrary command inside isolated profile runtime env. This does **not** change global active profile.
-
-```bash
-csp exec <name> -- <command> [args...]
-```
-
-**Examples:**
-
-Run any CLI tool with profile runtime env:
 ```bash
-csp exec work -- env
-csp exec work -- node scripts/check-env.js
-```
-
-Run a shell function/alias defined by your interactive shell:
-```bash
-csp exec hd -- claude-hd2
-```
-
-**Behavior:**
-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. On Unix-like systems, runs the command through your interactive shell so shell functions/aliases can resolve like a normal terminal command; on Windows, keeps direct spawn behavior with `.cmd` / `.bat` wrapper detection
-7. Reasserts `CLAUDE_CONFIG_DIR` and allowlisted `ANTHROPIC_*` after shell init so profile isolation wins over shell startup overrides
-8. Inherits stdin/stdout/stderr and forwards child exit code
-9. Keeps `.active` unchanged and never mutates global `~/.claude`
-
----
-
-### uninstall
-
-Remove all profiles and restore Claude Code to its pre-CSP state.
-
-```bash
-csp uninstall
-```
-
-**Options:**
-- `-f, --force` — Skip confirmation prompt
-- `--profile <name>` — Restore a specific profile instead of the active one
-
-**Examples:**
-
-Uninstall with confirmation:
-```bash
-csp uninstall
-# Uninstall CSP and remove all profiles? This cannot be undone. (y/N)
-```
-
-Restore a specific profile during uninstall:
-```bash
-csp uninstall --profile production
-```
-
-Force uninstall without prompt:
-```bash
-csp uninstall --force
+csp use work
+# Restart Claude Code for changes to take effect
 ```
 
-**Behavior:**
-1. Creates a final backup at `~/.claude-profiles/.backup/`
-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`
-
----
+- Mutates `~/.claude` directly
+- Updates `.active` marker
+- Requires Claude restart
 
 ## How Profiles Work
 
 ### Profile Storage
 
-Profiles are stored in `~/.claude-profiles/`:
-
 ```
 ~/.claude-profiles/
-├── .active                    # Current active profile name (legacy use mode)
+├── .active                    # Current active profile name (legacy)
 ├── profiles.json              # Metadata for all profiles (v2 schema)
 ├── .runtime/                  # Isolated launch roots
 │   ├── work/
@@ -640,329 +109,65 @@ Profiles are stored in `~/.claude-profiles/`:
 │   ├── source.json           # Managed item map
 │   ├── settings.json         # Copied from ~/.claude
 │   ├── .env                  # Copied from ~/.claude
-│   ├── .ck.json              # Copied from ~/.claude
-│   ├── .ckignore             # Copied from ~/.claude
-│   ├── commands/             # Copied from ~/.claude
-│   └── plugins/              # Copied from ~/.claude
+│   └── ...
 └── production/
     ├── source.json
-    ├── settings.json
     └── ...
 ```
 
 ### What Gets Managed
 
-**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`, `statusline.sh`, `statusline.ps1` — Custom statusline scripts
-- `.luna.json` — Luna configuration
-
-**Copied Files**:
-- `settings.json` — Editor settings
-- `.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/`, `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/`, `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
-
-### Legacy vs Isolated Launch Modes
-
-CSP now supports two paths:
-
-- **Legacy global mode (`csp use`)**
-  - Mutates `~/.claude`
-  - Updates `.active`
-  - Preserves old behavior for existing scripts
-
-- **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
-
-### Runtime Sync Policy (isolated launch)
-
-For each launch, CSP syncs static profile config into runtime root:
-
-- 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.
+| Category | Items |
+|---|---|
+| **Managed Static** | `CLAUDE.md`, `rules/`, `agents/`, `skills/`, `hooks/`, `statusline.*`, `.luna.json` |
+| **Copied Files** | `settings.json`, `.env`, `.ck.json`, `.ckignore`, `.mcp.json`, `.gitignore`, etc. |
+| **Copied Dirs** | `commands/`, `plugins/`, `workflows/`, `scripts/`, `output-styles/`, `schemas/` |
+| **Never Touched** | `.credentials.json`, `projects/`, `sessions/`, `cache/`, `telemetry/`, etc. |
 
 ## Safety Features
 
-### Lock File
-
-Prevents concurrent profile switches:
-- Created at `~/.claude-profiles/.lock` during operations
-- Contains process ID (PID) of the running operation
-- Auto-detects stale locks (process no longer running)
-- Throws error if another switch is in progress
-
-```
-Another csp operation is running (PID: 12345).
-Remove ~/.claude-profiles/.lock if stale.
-```
-
-### Claude Process Detection
-
-When switching profiles, CSP detects if Claude Code is running:
-
-```
-⚠ Claude Code appears to be running. Restart your Claude session after switching profiles.
-```
-
-**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
-
-During import, CSP also validates profile contents and rejects unsafe symlinks that point outside the imported profile tree.
-
-## Configuration via Environment Variables
-
-Override default behavior for testing or advanced use:
-
-### CSP_HOME
-
-Override the home directory (default: `process.env.HOME`).
-
-```bash
-CSP_HOME=/tmp/test csp list
-```
-
-### CSP_CLAUDE_DIR
-
-Override Claude config directory (default: `~/.claude`).
-
-```bash
-CSP_CLAUDE_DIR=/tmp/test-claude csp init
-```
-
-### CSP_PROFILES_DIR
-
-Override profiles storage directory (default: `~/.claude-profiles`).
-
-```bash
-CSP_PROFILES_DIR=/tmp/test-profiles csp list
-```
-
-**Use case:** Testing in isolated environments without affecting your real configuration.
+- **Lock file** — prevents concurrent profile switches (PID-based, auto-detects stale locks)
+- **Claude process detection** — warns when Claude is running during switch
+- **Import validation** — rejects unsafe symlinks pointing outside profile tree
+- **Profile validation** — checks structure before applying
+- **Auto-backups** — created before destructive operations
 
 ## Workflow Examples
 
-### Scenario 1: Work vs. Personal
+### Work vs. Personal
 
 ```bash
-# Initial setup
 csp init
-
-# Create work profile
-csp create work -d "Work environment with company rules"
-# ... modify rules, settings, etc. ...
-csp save
-
-# Create personal profile
-csp use default
+csp create work -d "Work environment"
 csp create personal -d "Personal projects"
-csp save
-
-# Switch between them
-csp use work      # Switch to work
-csp use personal  # Switch to personal
-```
 
-### Scenario 2: Testing New Tools
-
-```bash
-# Clone current profile
-csp create experimental --from default -d "Testing new Luna skills"
-
-# Switch and experiment
-csp use experimental
-# ... install new skills, modify rules ...
-csp save
-
-# If good, merge back to default
-csp diff current default
-# ... review differences ...
-csp use default
-# ... copy changes manually or recreate ...
-
-# Clean up
-csp delete experimental
+# Launch whichever you need
+csp launch work
+csp launch personal
 ```
 
-### Scenario 3: Backup and Restore
+### Backup and Restore
 
 ```bash
-# Backup production profile
 csp export production -o ~/backups/production-2026-03.tar.gz
-
-# ... time passes ...
-
-# Restore if needed
 csp import ~/backups/production-2026-03.tar.gz -n production-restored
-csp use production-restored
 ```
 
-### Scenario 4: Share Profile with Team
+### Share with Team
 
 ```bash
-# Export your setup
 csp export my-setup -o ./my-setup.csp.tar.gz
-
-# Teammate imports
+# Teammate:
 csp import my-setup.csp.tar.gz -n shared-team-setup
-csp use shared-team-setup
 ```
 
-## Troubleshooting
+## Documentation
 
-### No active profile
-
-**Error:** `No active profile. Run "csp create <name>" first.`
-
-**Solution:** Initialize with `csp init` to create the default profile.
-
-```bash
-csp init
-```
-
-### Profile doesn't exist
-
-**Error:** `Profile "name" does not exist. Run "csp list" to see available profiles.`
-
-**Solution:** Check available profiles and use exact name.
-
-```bash
-csp list
-csp use production  # if "production" exists
-```
-
-### Cannot delete default profile
-
-**Error:** `Cannot delete the default profile.`
-
-**Solution:** Keep `default` and delete only non-default profiles.
-
-```bash
-csp delete experimental
-```
-
-### Stale lock file
-
-**Error:** `Another csp operation is running (PID: 12345). Remove ~/.claude-profiles/.lock if stale.`
-
-**Solution:** If the process is not running, manually remove the lock:
-
-```bash
-rm ~/.claude-profiles/.lock
-```
-
-### Invalid profile structure
-
-**Error:** `Profile "name" is invalid: Missing source.json — no managed items defined`
-
-**Solution:** Recreate the profile or import a valid profile archive.
-
-### Changes not applying
-
-**Issue:** Switched profiles but changes don't appear in Claude Code.
-
-**Solution:** Restart Claude Code session after switching.
-
-```bash
-csp use staging
-# Close and restart Claude Code
-```
-
-## Development
-
-### Run Tests
-
-```bash
-npm test                # All tests
-npm run test:core       # Core library tests
-npm run test:cli        # CLI integration tests
-npm run test:safety     # Safety feature tests
-```
-
-### Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for version history and migration guidance.
-
-### Project Structure
-
-```
-.
-├── bin/
-│   └── csp.js                    # CLI entry point
-├── src/
-│   ├── commands/                 # Command implementations
-│   │   ├── init.js
-│   │   ├── current.js
-│   │   ├── list.js
-│   │   ├── status.js
-│   │   ├── create.js
-│   │   ├── save.js
-│   │   ├── use.js
-│   │   ├── toggle.js
-│   │   ├── delete.js
-│   │   ├── export.js
-│   │   ├── import.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
-│   ├── 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
-├── tests/
-│   ├── core-library.test.js
-│   ├── cli-integration.test.js
-│   └── safety.test.js
-└── package.json
-```
-
-## Planned / Future Features
-
-- Automatic backups during profile switch flow (`csp use`) with backup retention/pruning.
+- [Commands Reference](docs/commands-reference.md) — Full command options, behavior, and troubleshooting
+- [System Architecture](docs/system-architecture.md) — Module architecture, data flows, and internals
+- [Project Overview](docs/project-overview-pdr.md) — Product design review and requirements
+- [Code Standards](docs/code-standards.md) — Coding conventions and guidelines
+- [Changelog](CHANGELOG.md) — Version history and migration guidance
 
 ## License
 
@@ -970,8 +175,4 @@ MIT
 
 ## Contributing
 
-Contributions welcome! Please ensure tests pass and follow existing code style.
-
-```bash
-npm test
-```
+Contributions welcome! See the [docs/](docs/) for architecture and code standards.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-switch-profile",
-  "version": "1.4.8",
+  "version": "1.4.12",
   "description": "CLI tool for managing multiple Claude Code profiles",
   "type": "module",
   "bin": {

package/src/runtime-instance-manager.js

@@ -11,6 +11,7 @@ import {
   readlinkSync,
 } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
 import { MANAGED_ITEMS, COPY_ITEMS, COPY_DIRS, CLAUDE_DIR } from './constants.js';
 import {
   getActive,
@@ -76,6 +77,8 @@ const shouldSyncDir = (src, dest) => {
   }
 };
 
+const escapeRegExp = (string) => string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
 const replacePathVariants = (content, fromPath, toPath) => {
   const fromEscaped = fromPath.replaceAll('\\', '\\\\');
   const toEscaped = toPath.replaceAll('\\', '\\\\');
@@ -83,10 +86,20 @@ const replacePathVariants = (content, fromPath, toPath) => {
   const toFwd = toPath.replaceAll('\\', '/');
 
   let updated = content;
-  updated = updated.replaceAll(fromEscaped, toEscaped);
-  updated = updated.replaceAll(fromFwd, toFwd);
+
+  // Prevent matching substrings of other paths (e.g. ~/.claude matching ~/.claude-profiles)
+  // by ensuring it's not immediately followed by an alphanumeric character or hyphen.
+  const negativeLookahead = '(?![a-zA-Z0-9\\-])';
+
+  const replaceWithRegex = (str, targetF, targetT) => {
+    const re = new RegExp(escapeRegExp(targetF) + negativeLookahead, 'g');
+    return str.replace(re, targetT);
+  };
+
+  updated = replaceWithRegex(updated, fromEscaped, toEscaped);
+  updated = replaceWithRegex(updated, fromFwd, toFwd);
   if (fromPath !== fromEscaped) {
-    updated = updated.replaceAll(fromPath, toPath);
+    updated = replaceWithRegex(updated, fromPath, toPath);
   }
 
   return updated;
@@ -103,6 +116,25 @@ const rewriteSettingsForRuntime = (runtimeDir, sourceDir) => {
     updated = replacePathVariants(updated, sourceDir, runtimeDir);
     updated = replacePathVariants(updated, CLAUDE_DIR, runtimeDir);
 
+    // Also replace shell variable patterns commonly used in hook commands.
+    // Hook commands in settings.json often reference paths like:
+    //   $HOME/.claude/hooks/...  or  ${HOME}/.claude/hooks/...  or  ~/.claude/hooks/...
+    // These won't match the literal path replacement above.
+    const home = homedir();
+    const claudeRelSuffix = CLAUDE_DIR.startsWith(home) ? CLAUDE_DIR.slice(home.length) : '/.claude';
+
+    const shellPatterns = [
+      `$HOME${claudeRelSuffix}`,
+      `\${HOME}${claudeRelSuffix}`,
+      `~${claudeRelSuffix}`,
+    ];
+
+    for (const pattern of shellPatterns) {
+      if (updated.includes(pattern)) {
+        updated = updated.replaceAll(pattern, runtimeDir);
+      }
+    }
+
     if (updated !== raw) {
       writeFileSync(settingsPath, updated);
     }