@swarmify/agents-cli 1.3.13 → 1.4.0

package/README.md

@@ -1,20 +1,24 @@
 # @swarmify/agents-cli
 
-Dotfiles for AI coding agents. Sync prompts, MCP servers, hooks, and skills across Claude, Codex, Gemini, Cursor, and more.
+Your virtual environment manager for AI coding agents.
 
 ```bash
 npm install -g @swarmify/agents-cli
 ```
 
-## The Idea
+## The Problem
 
-You configure Claude Code manually. Then you switch to Codex or Gemini and start from scratch. This CLI syncs your setup across all agents:
+You spend hours configuring Claude Code: MCP servers, slash commands, hooks, skills. Then you switch to Codex or Gemini and start from scratch. Or you get a new machine and lose everything.
+
+## The Solution
+
+Keep your agent configuration in a git repo. Pull it anywhere.
 
 ```bash
-# Pull your config on a new machine
+# New machine? One command.
 agents pull gh:username/.agents
 
-# See what you have installed
+# See what's installed
 agents status claude
 ```
 
@@ -40,145 +44,166 @@ Installed MCP Servers
     User: Swarm@latest, GoDaddy
 ```
 
-## What Gets Synced
+Your `.agents` repo becomes the source of truth for all your AI coding tools.
 
-| Resource | Location | Synced To |
-|----------|----------|-----------|
-| Slash commands | `~/.claude/commands/` | Claude, Codex, Gemini |
-| MCP servers | `~/.claude/settings.json` | Claude, Codex, Gemini |
-| Hooks | `~/.claude/hooks.json` | Claude, Gemini |
-| Agent Skills | `~/.claude/skills/` | Claude, Codex, Gemini |
-| CLI versions | npm/brew | All agents |
+## What Gets Synced
 
-## Commands
+| Resource | Description | Agents |
+|----------|-------------|--------|
+| Slash commands | `/debug`, `/plan`, custom prompts | Claude, Codex, Gemini, Cursor, OpenCode |
+| MCP servers | Tools your agents can use | Claude, Codex, Gemini |
+| Hooks | Pre/post execution scripts | Claude, Gemini |
+| Skills | Reusable agent capabilities | Claude, Codex, Gemini |
+| CLI versions | Which version of each agent | All |
 
-### Prompts (Slash Commands)
+## Quick Start
 
 ```bash
-# List what's installed
-agents commands list
+# 1. Install
+npm install -g @swarmify/agents-cli
 
-# Install from a git repo
-agents commands add gh:user/my-prompts
+# 2. Set your config repo
+agents repo add gh:username/.agents
 
-# Remove
-agents commands remove my-command
+# 3. Pull everything
+agents pull
+
+# 4. Check what's installed
+agents status
 ```
 
-### MCP Servers
+## Your .agents Repo
+
+```
+.agents/
+  agents.yaml              # CLI versions, MCP servers, defaults
+  shared/commands/         # Slash commands for all agents
+  claude/commands/         # Claude-specific commands
+  claude/hooks/            # Claude hooks
+  codex/prompts/           # Codex-specific prompts
+  gemini/commands/         # Gemini commands (auto-converted to TOML)
+  skills/                  # Agent Skills (SKILL.md + rules/)
+```
+
+Example `agents.yaml`:
+
+```yaml
+clis:
+  claude:
+    package: "@anthropic-ai/claude-code"
+    version: "latest"
+  codex:
+    package: "@openai/codex"
+    version: "latest"
+
+mcp:
+  filesystem:
+    command: "npx -y @anthropic-ai/mcp-filesystem"
+    transport: stdio
+    scope: user
+    agents: [claude, codex, gemini]
+
+  memory:
+    command: "npx -y @anthropic-ai/mcp-memory"
+    transport: stdio
+    scope: user
+    agents: [claude, codex, gemini]
+
+defaults:
+  method: symlink
+  scope: user
+  agents: [claude, codex, gemini]
+```
+
+## Commands
+
+### Status
 
 ```bash
-# List servers across all agents
-agents mcp list
+agents status              # Full overview
+agents status --agent claude
+```
 
-# Add stdio server (use -- before the command)
-agents mcp add swarm -- npx @swarmify/agents-mcp
-agents mcp add memory -- npx -y @anthropic-ai/mcp-memory
+### Pull & Push
+
+```bash
+agents pull                # Sync from your repo
+agents pull --dry-run      # Preview changes
+agents push                # Push local changes back
+```
 
-# Add HTTP server with headers
-agents mcp add api https://api.example.com/mcp --transport http -H "Authorization:Bearer token"
+### Slash Commands
 
-# Remove from all agents
-agents mcp remove swarm
+```bash
+agents commands list
+agents commands add gh:user/my-commands
+agents commands remove my-command
+agents commands push my-command   # Promote project -> user scope
 ```
 
-### Hooks
+### MCP Servers
 
 ```bash
-# List hooks
-agents hooks list
+# List across all agents
+agents mcp list
 
-# Install from repo
-agents hooks add gh:user/my-hooks
+# Add (use -- before the command)
+agents mcp add memory -- npx -y @anthropic-ai/mcp-memory
+agents mcp add api https://api.example.com --transport http
+
+# Search registries
+agents search filesystem
+agents add mcp:@anthropic-ai/mcp-filesystem
 
 # Remove
-agents hooks remove my-hook
+agents mcp remove memory
 ```
 
 ### Skills
 
-Agent Skills are reusable capabilities (SKILL.md + rules/) that agents can invoke.
-
 ```bash
-# List installed skills
 agents skills list
-
-# Install from repo
 agents skills add gh:user/my-skills
-
-# Show details
 agents skills info my-skill
 ```
 
-### Search & Install from Registries
-
-Search public registries for MCP servers and skills:
+### Hooks
 
 ```bash
-# Search all registries
-agents search github
-agents search filesystem --limit 10
-
-# Filter by type
-agents search github --type mcp
-
-# Install from registry (auto-detected)
-agents add mcp:io.github.bytedance/mcp-server-filesystem
-
-# Or use identifiers
-agents add skill:user/my-skill    # Skill from git
-agents add gh:user/my-repo        # Git repo directly
+agents hooks list
+agents hooks add gh:user/my-hooks
+agents hooks remove my-hook
 ```
 
-### Registry Management
+### CLI Management
 
 ```bash
-# List configured registries
-agents registry list
-
-# Add custom registry
-agents registry add mcp myregistry https://api.example.com/v1
-
-# Configure API key
-agents registry config mcp myregistry --api-key YOUR_KEY
-
-# Disable/enable
-agents registry disable mcp myregistry
-agents registry enable mcp myregistry
-
-# Remove
-agents registry remove mcp myregistry
+agents cli list            # Show installed versions
+agents cli add claude      # Install agent CLI
+agents cli remove codex    # Uninstall agent CLI
+agents cli upgrade         # Upgrade all to latest
 ```
 
-Default registries:
-- `official` (MCP): https://registry.modelcontextprotocol.io
-
-### Sync
-
-```bash
-# Pull config from your .agents repo
-agents pull gh:username/.agents
+## Scopes
 
-# Push local changes back
-agents push
+Resources can exist at two levels:
 
-# Full status
-agents status
-```
+| Scope | Location | Use |
+|-------|----------|-----|
+| User | `~/.{agent}/` | Available everywhere |
+| Project | `./.{agent}/` | This repo only, committed |
 
-### CLI Management
+Promote project-scoped items to user scope:
 
 ```bash
-# Show installed versions
-agents cli list
-
-# Upgrade all to latest
-agents cli upgrade --latest
+agents commands push my-command
+agents mcp push my-server
+agents skills push my-skill
 ```
 
 ## Filtering
 
-All commands support `--agent` and `--scope` filters:
+All list commands support filters:
 
 ```bash
 agents commands list --agent claude
@@ -186,44 +211,38 @@ agents mcp list --scope project
 agents skills list --agent codex --scope user
 ```
 
-## Scopes
+## Registries
 
-| Scope | Location | Use Case |
-|-------|----------|----------|
-| User | `~/.{agent}/` | Available everywhere |
-| Project | `./.{agent}/` | This repo only |
-
-Promote project-scoped items to user scope:
+Search and install from public registries:
 
 ```bash
-agents commands push my-command
-agents mcp push my-server
+# Search
+agents search github --type mcp
+
+# Install from registry
+agents add mcp:@anthropic-ai/mcp-filesystem
+
+# Manage registries
+agents registry list
+agents registry add mcp myregistry https://api.example.com
+agents registry config mcp myregistry --api-key KEY
 ```
 
 ## Supported Agents
 
-| Agent | Prompts | MCP | Hooks | Skills |
-|-------|---------|-----|-------|--------|
+| Agent | Commands | MCP | Hooks | Skills |
+|-------|----------|-----|-------|--------|
 | Claude Code | Yes | Yes | Yes | Yes |
 | Codex | Yes | Yes | - | Yes |
-| Gemini CLI | Yes (TOML) | Yes | Yes | Yes |
-| Cursor | Yes | Yes | - | Yes |
-| OpenCode | Yes | Yes | - | Yes |
+| Gemini CLI | Yes | Yes | Yes | Yes |
+| Cursor | Yes | Yes | - | - |
+| OpenCode | Yes | Yes | - | - |
 
-## Your .agents Repo
-
-```
-.agents/
-  agents.yaml           # CLIs, MCP servers, defaults
-  shared/commands/      # Prompts for all agents
-  claude/commands/      # Claude-specific prompts
-  claude/hooks/         # Claude hooks
-  skills/               # Agent Skills
-```
+Format conversion is automatic. Write commands in markdown, they're converted to TOML for Gemini.
 
 ## Related
 
-- [@swarmify/agents-mcp](https://www.npmjs.com/package/@swarmify/agents-mcp) - Multi-agent orchestration MCP server
+- [@swarmify/agents-mcp](https://www.npmjs.com/package/@swarmify/agents-mcp) - MCP server for multi-agent orchestration
 
 ## License
 

package/dist/index.js

@@ -3,14 +3,14 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
 import { checkbox, confirm, select } from '@inquirer/prompts';
-import { AGENTS, ALL_AGENT_IDS, MCP_CAPABLE_AGENTS, SKILLS_CAPABLE_AGENTS, HOOKS_CAPABLE_AGENTS, getAllCliStates, isCliInstalled, isMcpRegistered, registerMcp, unregisterMcp, listInstalledMcpsWithScope, promoteMcpToUser, } from './lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, MCP_CAPABLE_AGENTS, SKILLS_CAPABLE_AGENTS, HOOKS_CAPABLE_AGENTS, getAllCliStates, isCliInstalled, getCliVersion, isMcpRegistered, registerMcp, unregisterMcp, listInstalledMcpsWithScope, promoteMcpToUser, } from './lib/agents.js';
 import { readManifest, writeManifest, createDefaultManifest, MANIFEST_FILENAME, } from './lib/manifest.js';
 import { readState, ensureAgentsDir, getRepoLocalPath, getScope, setScope, removeScope, getScopesByPriority, getScopePriority, } from './lib/state.js';
 import { SCOPE_PRIORITIES, DEFAULT_SYSTEM_REPO } from './lib/types.js';
 import { cloneRepo, parseSource } from './lib/git.js';
-import { discoverCommands, resolveCommandSource, installCommand, uninstallCommand, listInstalledCommandsWithScope, promoteCommandToUser, } from './lib/commands.js';
-import { discoverHooksFromRepo, installHooks, listInstalledHooksWithScope, promoteHookToUser, removeHook, } from './lib/hooks.js';
-import { discoverSkillsFromRepo, installSkill, uninstallSkill, listInstalledSkillsWithScope, promoteSkillToUser, getSkillInfo, getSkillRules, } from './lib/skills.js';
+import { discoverCommands, resolveCommandSource, installCommand, uninstallCommand, listInstalledCommandsWithScope, promoteCommandToUser, commandExists, } from './lib/commands.js';
+import { discoverHooksFromRepo, installHooks, listInstalledHooksWithScope, promoteHookToUser, removeHook, hookExists, } from './lib/hooks.js';
+import { discoverSkillsFromRepo, installSkill, uninstallSkill, listInstalledSkillsWithScope, promoteSkillToUser, getSkillInfo, getSkillRules, skillExists, } from './lib/skills.js';
 import { DEFAULT_REGISTRIES } from './lib/types.js';
 import { search as searchRegistries, getRegistries, setRegistry, removeRegistry, resolvePackage, } from './lib/registry.js';
 const program = new Command();
@@ -195,17 +195,14 @@ program
     }
     console.log();
 });
-// =============================================================================
-// PULL COMMAND
-// =============================================================================
 program
     .command('pull [source]')
     .description('Pull and sync from remote .agents repo')
     .option('-y, --yes', 'Skip interactive prompts')
-    .option('-f, --force', 'Overwrite local changes')
+    .option('-f, --force', 'Overwrite existing resources without asking')
     .option('-s, --scope <scope>', 'Target scope (default: user)', 'user')
     .option('--dry-run', 'Show what would change')
-    .option('--skip-clis', 'Skip CLI installation')
+    .option('--skip-clis', 'Skip CLI version sync')
     .option('--skip-mcp', 'Skip MCP registration')
     .action(async (source, options) => {
     const scopeName = options.scope;
@@ -233,6 +230,7 @@ program
     // Prevent modification of readonly scopes (but allow syncing from them)
     const targetScopeConfig = meta.scopes[effectiveScope];
     const isReadonly = targetScopeConfig?.readonly || effectiveScope === 'system';
+    const isUserScope = effectiveScope === 'user';
     const parsed = parseSource(targetSource);
     const spinner = ora(`Syncing from ${effectiveScope} scope...`).start();
     try {
@@ -321,47 +319,176 @@ program
                 default: manifest?.defaults?.method || 'symlink',
             });
         }
-        const defaultAgents = selectedAgents;
+        // Detect conflicts
+        const conflicts = [];
+        // Check command conflicts
+        for (const command of commands) {
+            for (const agentId of selectedAgents) {
+                if (!isCliInstalled(agentId) && agentId !== 'cursor')
+                    continue;
+                const sourcePath = resolveCommandSource(localPath, command.name, agentId);
+                if (sourcePath && commandExists(agentId, command.name)) {
+                    conflicts.push({ type: 'command', name: command.name, agent: agentId });
+                }
+            }
+        }
+        // Check skill conflicts
+        for (const skill of skills) {
+            const skillAgents = SKILLS_CAPABLE_AGENTS.filter((id) => selectedAgents.includes(id) && (isCliInstalled(id) || id === 'cursor'));
+            for (const agentId of skillAgents) {
+                if (skillExists(agentId, skill.name)) {
+                    conflicts.push({ type: 'skill', name: skill.name, agent: agentId });
+                }
+            }
+        }
+        // Check hook conflicts
+        const hookAgents = selectedAgents.filter((id) => HOOKS_CAPABLE_AGENTS.includes(id) && isCliInstalled(id));
+        for (const hookName of discoveredHooks.shared) {
+            for (const agentId of hookAgents) {
+                if (hookExists(agentId, hookName)) {
+                    conflicts.push({ type: 'hook', name: hookName, agent: agentId });
+                }
+            }
+        }
+        for (const [agentIdStr, hookNames] of Object.entries(discoveredHooks.agentSpecific)) {
+            const agentId = agentIdStr;
+            if (hookAgents.includes(agentId)) {
+                for (const hookName of hookNames) {
+                    if (hookExists(agentId, hookName)) {
+                        conflicts.push({ type: 'hook', name: hookName, agent: agentId });
+                    }
+                }
+            }
+        }
+        // Check MCP conflicts
+        if (!options.skipMcp && manifest?.mcp) {
+            for (const [name, config] of Object.entries(manifest.mcp)) {
+                if (config.transport === 'http' || !config.command)
+                    continue;
+                for (const agentId of config.agents) {
+                    if (!isCliInstalled(agentId))
+                        continue;
+                    if (isMcpRegistered(agentId, name)) {
+                        conflicts.push({ type: 'mcp', name, agent: agentId });
+                    }
+                }
+            }
+        }
+        // Handle conflicts
+        let conflictAction = 'overwrite';
+        if (conflicts.length > 0 && !options.force) {
+            // Deduplicate conflicts by name (show each resource once, not per-agent)
+            const uniqueConflicts = new Map();
+            for (const c of conflicts) {
+                const key = `${c.type}:${c.name}`;
+                if (!uniqueConflicts.has(key)) {
+                    uniqueConflicts.set(key, c);
+                }
+            }
+            console.log(chalk.yellow(`\nFound ${uniqueConflicts.size} existing resources that would be overwritten:\n`));
+            const byType = {
+                command: [],
+                skill: [],
+                hook: [],
+                mcp: [],
+            };
+            for (const c of uniqueConflicts.values()) {
+                byType[c.type].push(c.name);
+            }
+            if (byType.command.length > 0) {
+                console.log(`  Commands: ${byType.command.join(', ')}`);
+            }
+            if (byType.skill.length > 0) {
+                console.log(`  Skills: ${byType.skill.join(', ')}`);
+            }
+            if (byType.hook.length > 0) {
+                console.log(`  Hooks: ${byType.hook.join(', ')}`);
+            }
+            if (byType.mcp.length > 0) {
+                console.log(`  MCP Servers: ${byType.mcp.join(', ')}`);
+            }
+            if (!options.yes) {
+                conflictAction = await select({
+                    message: 'How do you want to handle existing resources?',
+                    choices: [
+                        { name: 'Overwrite all', value: 'overwrite' },
+                        { name: 'Skip existing (only install new)', value: 'skip' },
+                        { name: 'Cancel', value: 'cancel' },
+                    ],
+                });
+                if (conflictAction === 'cancel') {
+                    console.log(chalk.yellow('\nSync cancelled'));
+                    return;
+                }
+            }
+        }
+        const skipExisting = conflictAction === 'skip';
+        const conflictNames = new Set(conflicts.map((c) => `${c.type}:${c.name}:${c.agent}`));
+        // Install commands
         const installSpinner = ora('Installing commands...').start();
         let installed = 0;
+        let skipped = 0;
         for (const command of commands) {
-            for (const agentId of defaultAgents) {
+            for (const agentId of selectedAgents) {
                 if (!isCliInstalled(agentId) && agentId !== 'cursor')
                     continue;
                 const sourcePath = resolveCommandSource(localPath, command.name, agentId);
-                if (sourcePath) {
-                    installCommand(sourcePath, agentId, command.name, method);
-                    installed++;
+                if (!sourcePath)
+                    continue;
+                const conflictKey = `command:${command.name}:${agentId}`;
+                if (skipExisting && conflictNames.has(conflictKey)) {
+                    skipped++;
+                    continue;
                 }
+                installCommand(sourcePath, agentId, command.name, method);
+                installed++;
             }
         }
-        installSpinner.succeed(`Installed ${installed} command instances`);
+        if (skipped > 0) {
+            installSpinner.succeed(`Installed ${installed} commands (skipped ${skipped} existing)`);
+        }
+        else {
+            installSpinner.succeed(`Installed ${installed} command instances`);
+        }
         // Install skills
         if (skills.length > 0) {
             const skillSpinner = ora('Installing skills...').start();
             let skillsInstalled = 0;
+            let skillsSkipped = 0;
             for (const skill of skills) {
                 const skillAgents = SKILLS_CAPABLE_AGENTS.filter((id) => selectedAgents.includes(id) && (isCliInstalled(id) || id === 'cursor'));
+                // Check if should skip
+                const shouldSkip = skipExisting && skillAgents.some((agentId) => conflictNames.has(`skill:${skill.name}:${agentId}`));
+                if (shouldSkip) {
+                    skillsSkipped++;
+                    continue;
+                }
                 if (skillAgents.length > 0) {
                     const result = installSkill(skill.path, skill.name, skillAgents);
                     if (result.success)
                         skillsInstalled++;
                 }
             }
-            skillSpinner.succeed(`Installed ${skillsInstalled} skills`);
-        }
-        // Install hooks
-        if (totalHooks > 0) {
-            const hookAgents = selectedAgents.filter((id) => HOOKS_CAPABLE_AGENTS.includes(id) && isCliInstalled(id));
-            if (hookAgents.length > 0) {
-                const hookSpinner = ora('Installing hooks...').start();
-                const result = await installHooks(localPath, hookAgents, { scope: 'user' });
-                hookSpinner.succeed(`Installed ${result.installed.length} hooks`);
+            if (skillsSkipped > 0) {
+                skillSpinner.succeed(`Installed ${skillsInstalled} skills (skipped ${skillsSkipped} existing)`);
+            }
+            else {
+                skillSpinner.succeed(`Installed ${skillsInstalled} skills`);
             }
         }
+        // Install hooks
+        if (totalHooks > 0 && hookAgents.length > 0) {
+            const hookSpinner = ora('Installing hooks...').start();
+            // Note: installHooks handles its own conflict detection internally
+            // For now, pass the full list - in the future we could filter
+            const result = await installHooks(localPath, hookAgents, { scope: 'user' });
+            hookSpinner.succeed(`Installed ${result.installed.length} hooks`);
+        }
+        // Register MCP servers
         if (!options.skipMcp && manifest?.mcp) {
             const mcpSpinner = ora('Registering MCP servers...').start();
             let registered = 0;
+            let mcpSkipped = 0;
             for (const [name, config] of Object.entries(manifest.mcp)) {
                 // Skip HTTP transport MCPs for now (need different registration)
                 if (config.transport === 'http' || !config.command)
@@ -369,14 +496,55 @@ program
                 for (const agentId of config.agents) {
                     if (!isCliInstalled(agentId))
                         continue;
-                    if (isMcpRegistered(agentId, name))
-                        continue;
+                    const conflictKey = `mcp:${name}:${agentId}`;
+                    if (conflictNames.has(conflictKey)) {
+                        if (skipExisting) {
+                            mcpSkipped++;
+                            continue;
+                        }
+                        // If overwriting, unregister first then re-register
+                        unregisterMcp(agentId, name);
+                    }
                     const result = registerMcp(agentId, name, config.command, config.scope);
                     if (result.success)
                         registered++;
                 }
             }
-            mcpSpinner.succeed(`Registered ${registered} MCP servers`);
+            if (mcpSkipped > 0) {
+                mcpSpinner.succeed(`Registered ${registered} MCP servers (skipped ${mcpSkipped} existing)`);
+            }
+            else {
+                mcpSpinner.succeed(`Registered ${registered} MCP servers`);
+            }
+        }
+        // Sync CLI versions (user scope only, unless --skip-clis)
+        if (isUserScope && !options.skipClis && manifest?.clis) {
+            const cliSpinner = ora('Checking CLI versions...').start();
+            const cliUpdates = [];
+            for (const [agentIdStr, cliConfig] of Object.entries(manifest.clis)) {
+                const agentId = agentIdStr;
+                const agent = AGENTS[agentId];
+                if (!agent || !cliConfig.package)
+                    continue;
+                const currentVersion = getCliVersion(agentId);
+                const targetVersion = cliConfig.version;
+                // Skip if same version or if target is "latest" and CLI is installed
+                if (currentVersion === targetVersion)
+                    continue;
+                if (targetVersion === 'latest' && currentVersion)
+                    continue;
+                cliUpdates.push(`${agent.name}: ${currentVersion || 'not installed'} -> ${targetVersion}`);
+            }
+            if (cliUpdates.length > 0) {
+                cliSpinner.info('CLI version differences detected');
+                console.log(chalk.gray('  Run `agents cli upgrade` to update CLIs'));
+                for (const update of cliUpdates) {
+                    console.log(chalk.gray(`    ${update}`));
+                }
+            }
+            else {
+                cliSpinner.succeed('CLI versions match');
+            }
         }
         // Update scope config (only if not readonly)
         if (!isReadonly) {