claude-multi 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,98 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-05-22
+
+### Changed
+- **Interactive-first launch**: Running `claude-multi` with no arguments now opens the Ink TUI directly instead of printing help text
+  - CLI subcommands (`add`, `remove`, `list`, etc.) continue to work as before
+  - `--help` and `--version` flags are unaffected
+  - `CLAUDE_MULTI_INK=false` still falls back to the `prompts`-based interactive mode
+
+## [0.5.0] - 2026-05-14
+
+### Added
+- **Ink-based Interactive UI**: Full terminal UI built with Ink + React
+  - Home screen with instance list, menu, and health warning banner
+  - Animated components: Header, StatusBar, StepIndicator, InstanceCard, IssueCard, WarningBanner
+  - Screens: AddInstance, RemoveInstance, ShowInstanceInfo, ToggleAutoSync, FixSymlinks, HealthScreen, ManagePlugins, ManageMcp, ListInstances
+  - Keyboard navigation: arrow keys, Enter, ESC, `!` for health, `q` to quit
+  - `useConfig`, `useNavigation`, `useHealthCheck`, `useAnimations` hooks
+- **Per-Instance Plugin Management**: Granular plugin control per instance
+  - `PluginInfo` interface with id, name, category (internal/external), hasMcp, mcpServerNames, enabled, isSymlink
+  - `scanPluginsFromDir()` discovers plugins from both `plugins/` and `external_plugins/` subdirs
+  - `listDefaultPlugins()` / `listInstancePlugins()` for querying available and installed plugins
+  - `copySinglePlugin()` / `copySelectedPlugins()` for individual or batch install with rollback
+  - `removeSinglePlugin()` with rename-to-backup safety pattern
+  - `detectMcpCollisions()` to check MCP server name conflicts before install
+  - `validatePluginOperation()` pre-flight checks (configDir, symlink, plugin existence, collisions)
+  - Handles 12 internal LSP plugins without `plugin.json` (falls back to dir name)
+  - Supports both flat `{"serverName": config}` and nested `{"mcpServers": {"serverName": config}}` `.mcp.json` formats
+  - Coordinates with `installed_plugins.json` v2 format (scope, installPath, version, timestamps)
+  - Symlink detection: refuses per-plugin operations when auto-sync is active
+- **Migration System** (`src/migration.ts`): Safe v1 → v2 config upgrade
+  - `runMigration()` with 4-step procedure: backup → validate → transform → save
+  - PID-based lock file prevents concurrent migrations
+  - Automatic backup of config.json + instance settings.json (keeps last 3)
+  - Failure flag: sets `migrationStatus: "failed"` with error details, prevents auto-retry
+  - `clearMigrationFailure()` for explicit retry
+  - `CLAUDE_MULTI_HOME` env override for testability
+- **Health Check System** (`src/health.ts`): Detects and reports issues
+  - Checks: migration failure, missing configDir, missing binary, corrupted settings.json, broken symlinks
+  - Persistent health status at `~/.claude-multi/health-status.json`
+  - `dismissIssue()` / `dismissAllIssues()` for acknowledging warnings
+  - Warning banner on home screen with `!` key to review
+  - HealthScreen with list/detail views, retry, dismiss actions
+- **ManagePlugins Screen**: Full plugin management UI
+  - Install plugins from default (MultiSelect with MCP badge, [ext] tag)
+  - Remove installed plugins
+  - Enable/disable plugins
+  - List installed plugins with status indicators
+  - Symlink detection with warning
+- **ManageMcp Screen**: Enhanced MCP server management
+  - List MCP servers with source attribution ([pluginName] or [custom])
+  - Add custom MCP server (name + JSON config input)
+  - Remove custom MCP server (select from custom servers)
+  - Verify MCP configuration
+  - Copy between instances
+- **CLI Plugin Commands**: 5 new `plugins` sub-commands
+  - `plugins install <instance> <ids...>` — install plugins with collision detection
+  - `plugins remove <instance> <ids...>` — remove plugins with symlink guard
+  - `plugins list-defaults` — list all 50 default plugins with category/MCP badges
+  - `plugins list-installed [instance]` — list installed plugins per instance
+  - `plugins check-collisions <instance> <ids...>` — detect MCP name conflicts
+- **Provider Templates**: DeepSeek provider template added
+- **Instance State**: `initializeInstanceState()` creates `.claude.json` with `hasCompletedOnboarding: true`
+- **Provider Env**: `mergeProviderEnv()` integrates provider template env vars into instance settings
+- **Screenshot Capture**: `scripts/capture-screens.tsx` for automated UI screenshots
+
+### Changed
+- `copyAllFromDefault()` restored `autoSync` parameter for symlink-based plugin sync
+- `syncPluginsAndSkills()` creates actual symlinks instead of copying files
+- Broken symlink detection uses `lstatSync` (works when `existsSync` returns false)
+- `~/.claude` is strictly read-only — never modified by any operation
+- Atomic file writes for both config.json and settings.json (temp-file-rename pattern)
+- Lazy path resolution in migration.ts and health.ts for testability
+
+### Fixed
+- `syncPluginsAndSkills` was doing recursive copy instead of creating symlinks
+- `copyAllFromDefault` `autoSync` parameter was removed, breaking symlink-based sync
+- Broken symlinks not cleaned before creating new ones (used `lstatSync` instead of `existsSync`)
+- `isClaudeCodeRunning()` blocked tests — skips in `NODE_ENV=test`
+- `writeFileSync` not imported in config.ts
+- `McpSourceDetails` prop name mismatch in ManageMcp
+- `renameSync` dynamic import in `saveConfigAtomic` replaced with top-level import
+- TypeScript: `updateInstanceAutoSync` object possibly undefined after bounds check
+
+### Tests
+- **155 tests, 0 failures** across 16 test files
+- `test/plugin-management.test.ts` (18 tests): scanning, copy, remove, MCP helpers, atomic writes
+- `test/e2e/plugin-flow.test.ts` (6 tests): CLI plugin operations end-to-end
+- `test/migration.test.ts` (15 tests): migration, backup, lock, failure recovery
+- `test/health.test.ts` (15 tests): health checks, persistence, dismiss
+- `test/ink/` (31 tests): component rendering, screen navigation, animation hooks
+- `test/config.test.ts` (53 tests): sync/unsync, copyAllFromDefault, symlink cycles
+
 ## [0.4.3] - 2026-01-26
 
 ### Added
@@ -139,6 +231,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for custom config and binary paths
 - Command-line interface built with Commander.js
 
+[0.5.0]: https://github.com/hmziqrs/claude-multi/compare/v0.4.4...v0.5.0
+[0.4.4]: https://github.com/hmziqrs/claude-multi/compare/v0.4.3...v0.4.4
 [0.3.0]: https://github.com/hmziqrs/claude-multi/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/hmziqrs/claude-multi/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/hmziqrs/claude-multi/releases/tag/v0.1.0

package/README.md

@@ -1,231 +1,114 @@
-# claude-multi
+<div align="center">
 
-> Manage multiple Claude Code instances with different aliases and configurations
+<img src="public/favicon-animated.svg" width="256" height="256" alt="claude-multi logo">
 
-## Why?
+# claude-multi
 
-Claude Code supports multiple AI providers (Anthropic, GLM, Minimax), but switching between them requires manually editing config files. **claude-multi** solves this by creating isolated instances with different aliases and config paths.
+</div>
 
-## Features
+Run multiple Claude Code instances side by side — each with its own provider, config, and `claude-<name>` command.
 
-- 🔄 **Multiple Instances**: Run different Claude Code configs simultaneously
-- 🎯 **Simple CLI**: Easy-to-use commands for managing instances
-- 🔒 **Isolated Configs**: Each instance has its own settings and history
-- 🎨 **Provider Templates**: Built-in templates for GLM, MiniMax, and more
-- ✅ **Legal**: Uses wrapper scripts, no code modification
-- 🚀 **Auto-sync**: Always uses the latest official Claude Code
+Switching providers (Anthropic, GLM, MiniMax, DeepSeek) normally means editing `settings.json` by hand. This tool gives each one its own isolated install instead.
 
-## Installation
+## Install
 
 ```bash
-npm install -g claude-multi
+bun add -g claude-multi
 ```
 
-## Quick Start
-
-Get started with a provider template in 30 seconds:
-
 ```bash
-# Create a GLM instance
-claude-multi add glm --provider glm --api-key "your-glm-api-key"
-
-# Use it!
-claude-glm --help
+npm install -g claude-multi
 ```
 
-**Or use interactive mode:**
-
 ```bash
-claude-multi add myinstance
-# Choose "Yes" when asked about provider templates
-# Select GLM or MiniMax
-# Enter your API key
-# Done!
+pnpm add -g claude-multi
 ```
 
-### Windows Setup
-
-On Windows, ensure `%APPDATA%\npm` is in your PATH to use the wrapper commands:
-
-```cmd
-# Check if npm directory is in PATH
-echo %PATH%
-
-# Add to PATH if needed (PowerShell as Administrator)
-[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:APPDATA\npm", "User")
+```bash
+deno install -g -A -n claude-multi npm:claude-multi
 ```
 
-After adding to PATH, restart your terminal for changes to take effect.
+Requires Node 18+ (or Bun 1+) and `@anthropic-ai/claude-code` installed globally.
 
 ## Usage
 
-### Create instances
+Just run it — the interactive TUI opens by default:
 
 ```bash
-# Create instance (interactive - prompts for provider templates and copying settings)
-claude-multi add glm
-
-# Create instance with provider template (CLI mode)
-claude-multi add glm --provider glm --api-key "your-api-key-here"
-claude-multi add minimax --provider minimax --api-key "your-api-key-here"
-
-# Create instance with custom config path
-claude-multi add work --config ~/configs/claude-work
-
-# Create instance with custom binary path
-claude-multi add minimax --binary ~/.local/bin/claude-minimax
-
-# Non-interactive modes
-claude-multi add glm --copy-settings      # Copy only settings.json
-claude-multi add glm --copy-all           # Copy all files (settings, CLAUDE.md, plugins)
-claude-multi add glm --skip-prompts       # Start fresh, no prompts
+claude-multi
 ```
 
-**Provider Templates:**
-- **GLM (智谱AI)**: GLM-4.5-air and GLM-4.6 models via z.ai
-- **MiniMax**: MiniMax-M2 model via minimax.io
-
-**Interactive prompt options:**
-- **Provider templates**: Choose GLM, MiniMax, or None/Custom
-- **Nothing - start fresh**: Empty config directory
-- **Only settings.json**: Copy your settings (API keys, preferences)
-- **All files**: Copy settings, CLAUDE.md, plugins, etc. (excludes history, debug logs)
+You get a full terminal UI to add instances, manage plugins, configure MCP servers, and more. No subcommand needed.
 
-When using a provider template, you'll be prompted to enter your API key securely.
-
-### Use instances
-
-Each instance gets its own command:
+**Adding an instance** — pick it from the menu, or run directly:
 
 ```bash
-claude-glm       # Uses ~/.claude-glm config
-claude-work      # Uses ~/configs/claude-work
-claude-minimax   # Uses ~/.claude-minimax config
-claude           # Original command, uses ~/.claude
+claude-multi add glm
 ```
 
-### Manage instances
+No flags = the guided wizard walks you through provider, API key, and copy options. Then use your new instance:
 
 ```bash
-# List all instances
-claude-multi list
-
-# Show instance details
-claude-multi info glm
-
-# Remove instance
-claude-multi remove glm
-
-# Remove without confirmation
-claude-multi remove glm --force
+claude-glm
 ```
 
-### Version management
+## CLI (non-interactive)
+
+For scripting and automation, all operations are available as flags:
 
 ```bash
-# Check for updates
+# Instances
+claude-multi add <name> --provider glm --api-key "sk-..."
+claude-multi add <name> --config ~/path        # custom config dir
+claude-multi add <name> --copy-settings        # seed from ~/.claude
+claude-multi add <name> --copy-all             # copy everything + auto-sync
+claude-multi add <name> --skip-prompts         # start fresh, no wizard
+claude-multi add <name> --manual               # copy files instead of symlinking
+claude-multi list
+claude-multi info <name>
+claude-multi remove <name> [--force]
+
+# Plugins & MCP
+claude-multi plugins list
+claude-multi plugins enable <name> <plugin-id>
+claude-multi plugins disable <name> <plugin-id>
+claude-multi plugins copy <name>               # copy from default ~/.claude
+claude-multi mcp list
+claude-multi mcp copy <src> <dst>
+
+# Sync
+claude-multi auto-sync <name> on|off           # symlink plugins/skills from ~/.claude
+claude-multi fix-symlinks --all
+
+# Claude Code itself
 claude-multi version
-
-# Update Claude Code to latest
 claude-multi update
 ```
 
-## Use Cases
+Set `CLAUDE_MULTI_INK=false` to force the simpler prompts-based UI instead of the Ink TUI.
 
-### Personal + Work
-```bash
-claude-multi add personal
-claude-multi add work
-
-claude-personal  # Personal projects
-claude-work      # Work projects
-```
-
-### Different AI Providers
-```bash
-# Interactive mode with provider template
-claude-multi add anthropic  # Use Anthropic (prompted for API key)
-claude-multi add glm        # Use GLM template (prompted for API key)
-claude-multi add minimax    # Use MiniMax template (prompted for API key)
-
-# CLI mode with provider template
-claude-multi add glm --provider glm --api-key "sk-..."
-claude-multi add minimax --provider minimax --api-key "sk-..."
-
-claude-anthropic  # Uses Anthropic Claude
-claude-glm        # Uses GLM-4.6
-claude-minimax    # Uses MiniMax-M2
-```
-
-### Multiple Environments
-```bash
-claude-multi add prod
-claude-multi add staging
-claude-multi add dev
-
-# Different configs for each
-```
-
-## Provider Templates
+## Providers
 
-Built-in templates for popular AI providers. Each template auto-configures the API endpoint, model mappings, and optimal settings.
+| Provider | Endpoint |
+|---|---|
+| GLM (智谱AI) | `api.z.ai` |
+| MiniMax | `api.minimax.io` |
+| DeepSeek | `api.deepseek.com` |
 
-### Available Providers
+Templates write `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`, and related env vars to `~/.claude-<name>/settings.json`. Edit that file to customize.
 
-**GLM (智谱AI)**: GLM-4.5-air and GLM-4.6 models via `api.z.ai`
+## How it works
 
-**MiniMax**: MiniMax-M2 model via `api.minimax.io`
-
-### Usage
-
-```bash
-# CLI mode
-claude-multi add glm --provider glm --api-key "your-api-key"
+Each instance gets a config dir at `~/.claude-<name>/` and a wrapper script at `~/.local/bin/claude-<name>`. The wrapper sets `CLAUDE_CONFIG_DIR` before launching the unmodified `claude` binary — no forking, no patching.
 
-# Interactive mode
-claude-multi add myinstance
-# Select provider when prompted and enter API key
+```js
+#!/usr/bin/env bun
+process.env.CLAUDE_CONFIG_DIR = "/Users/you/.claude-glm"
+spawn("claude", process.argv.slice(2), { stdio: "inherit", env: process.env })
 ```
 
-Customize later by editing `~/.claude-{name}/settings.json`
-
-## Requirements
-
-- Node.js >= 18
-- `@anthropic-ai/claude-code` installed globally
-
-## Platform Support
-
-**claude-multi** supports all major operating systems:
-
-- ✅ **Linux**: Fully supported
-- ✅ **macOS**: Fully supported  
-- ✅ **Windows**: Fully supported
-
-### Platform-Specific Notes
-
-**Windows:**
-- Wrapper scripts are created as `.cmd` batch files
-- Binary path defaults to `%APPDATA%\npm`
-- Example: `claude-glm.cmd` instead of `claude-glm`
-
-**Unix/Linux/macOS:**
-- Wrapper scripts are Node.js scripts with shebangs
-- Binary path defaults to `~/.local/bin`
-- Scripts are automatically marked as executable
+Instance metadata lives in `~/.claude-multi/config.json`. With auto-sync on, `plugins/` and `skills/` are symlinked from `~/.claude/`, so installing a plugin once makes it available everywhere.
 
 ## License
 
 MIT
-
-## Credits
-
-Built with [Bun](https://bun.sh) and [Commander.js](https://github.com/tj/commander.js)
-
-Wrapper for [@anthropic-ai/claude-code](https://www.npmjs.com/package/@anthropic-ai/claude-code)
-
-## Support
-
-For technical documentation, development setup, and contribution guidelines, see [development.md](development.md).
-
-For issues, questions, or feature requests, please visit the project's issue tracker.

package/astro.config.mjs

@@ -0,0 +1,69 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  site: 'https://claudemutli.hmziq.xyz',
+  srcDir: './src/web',
+  vite: {
+    plugins: [tailwindcss()],
+    build: {
+      rollupOptions: {
+        output: {
+          manualChunks(id) {
+            if (id.includes('node_modules/three')) return 'three';
+          },
+        },
+      },
+    },
+  },
+  integrations: [
+    starlight({
+      title: 'claude-multi',
+      description:
+        'Manage multiple Claude Code instances with different AI providers and configurations',
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/hmziqrs/claude-multi',
+        },
+      ],
+      editLink: {
+        baseUrl: 'https://github.com/hmziqrs/claude-multi/edit/main/',
+      },
+      sidebar: [
+        {
+          label: 'Getting Started',
+          items: [{ slug: 'docs/getting-started' }],
+        },
+        {
+          label: 'Guides',
+          items: [
+            { slug: 'docs/usage' },
+            { slug: 'docs/providers' },
+            { slug: 'docs/how-it-works' },
+            { slug: 'docs/plugins-mcp' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { slug: 'docs/configuration' },
+            { slug: 'docs/changelog' },
+          ],
+        },
+        {
+          label: 'Development',
+          collapsed: true,
+          items: [
+            { slug: 'docs/development/subagent-model-plan' },
+          ],
+        },
+      ],
+      customCss: ['/src/web/styles/starlight.css'],
+      lastUpdated: true,
+      favicon: '/favicon.svg',
+    }),
+  ],
+});