@swarmify/agents-cli 1.5.13 → 1.5.14

package/README.md

@@ -1,10 +1,8 @@
 # @swarmify/agents-cli
 
-Your virtual environment manager for AI coding agents.
+**One config for all your AI coding agents.** Sync CLIs, MCP servers, commands, hooks, and skills across Claude, Codex, Gemini, and Cursor.
 
-Homepage: https://swarmify.co/#agents-cli
-NPM: https://www.npmjs.com/package/@swarmify/agents-cli
-VS Code Extension: [Agents](https://marketplace.visualstudio.com/items?itemName=swarmify.swarm-ext) - full-screen agent terminals with sub-agent spawning
+[Homepage](https://swarmify.co/#agents-cli) | [NPM](https://www.npmjs.com/package/@swarmify/agents-cli) | [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=swarmify.swarm-ext)
 
 ```bash
 npm install -g @swarmify/agents-cli
@@ -12,11 +10,39 @@ npm install -g @swarmify/agents-cli
 
 ## The Problem
 
-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.
+Each agent stores config differently. Different paths, different formats:
+
+| What | Claude | Codex | Gemini |
+|------|--------|-------|--------|
+| Commands | `~/.claude/commands/` (md) | `~/.codex/prompts/` (md) | `~/.gemini/commands/` (TOML) |
+| MCP config | `~/.claude/settings.json` | `~/.codex/config.json` | `~/.gemini/settings.json` |
+| Hooks | `~/.claude/hooks/` | - | `~/.gemini/hooks/` |
+
+You spend hours configuring Claude Code - MCP servers, slash commands, hooks, skills. Then you switch to Codex and start from scratch. Get a new machine and lose everything.
 
 ## The Solution
 
-One command to configure all your agents.
+```
+                      .agents repo (GitHub)
+                             |
+            +----------------+----------------+
+            |                |                |
+      agents.yaml      commands/          hooks/
+     (CLIs, MCPs)     (slash cmds)       (scripts)
+            |                |                |
+            +----------------+----------------+
+                             |
+                       agents pull
+                             |
+         +-------------------+-------------------+
+         |                   |                   |
+    ~/.claude/          ~/.codex/          ~/.gemini/
+  - commands/ (md)    - prompts/ (md)    - commands/ (TOML)
+  - hooks/            - config.json      - hooks/
+  - settings.json                        - settings.json
+```
+
+One repo. One command. All agents configured.
 
 ```bash
 # New machine? One command.
@@ -30,25 +56,26 @@ agents status
 Agent CLIs
 
   Claude Code    2.0.65
+  Codex          1.0.3
+  Gemini CLI     0.1.15
 
 Installed Commands
 
-  Claude Code:
-    User: clean, debug, plan, recap, ship, spawn, test, verify
-    Project: eval
+  Claude Code:   clean, debug, plan, ship, test
+  Codex:         clean, debug, plan, ship, test
+  Gemini CLI:    clean, debug, plan, ship, test
 
-Installed Skills
+Installed MCP Servers
 
-  Claude Code:
-    User: remotion-best-practices, vercel-react-best-practices
+  All agents:    Swarm, filesystem, memory
 
-Installed MCP Servers
+Installed Hooks
 
-  Claude Code:
-    User: Swarm@latest, GoDaddy
+  Claude Code:   pre-commit, post-tool
+  Gemini CLI:    pre-commit, post-tool
 ```
 
-Your `.agents` repo becomes the source of truth for all your AI coding tools.
+Write commands once in markdown - auto-converts to TOML for Gemini. Define MCP servers once - installs to all agents. Your `.agents` repo becomes the single source of truth.
 
 ## What Gets Synced
 
@@ -266,6 +293,64 @@ agents registry config mcp myregistry --api-key KEY
 
 Format conversion is automatic. Write commands in markdown, they're converted to TOML for Gemini.
 
+## Roadmap: Context Drives
+
+Sync your docs, research, and chat history across machines and teams.
+
+```
+~/.agents/
+  drives/                    # Context drives (synced)
+    work/
+      .context               # Per-drive settings
+      docs/
+      research/
+      specs/
+    personal/
+      .context
+      notes/
+
+  sessions/                  # Agent chat history (synced)
+    claude/
+    codex/
+    gemini/
+```
+
+**Why not just Google Drive?**
+
+| Feature | Google Drive | Context Drives |
+|---------|--------------|----------------|
+| Sync files | Yes | Yes |
+| Real-time collab | Yes (Docs only) | Yes (CRDT for all files) |
+| Agent session sync | No | Yes |
+| Checkpointing | No | Yes (snapshot & rollback) |
+| Per-directory conflict strategy | No | Yes (`.context` file) |
+| Designed for AI agents | No | Yes |
+
+**Conflict resolution strategies** (configurable per directory):
+
+```yaml
+# .context file
+strategy: crdt              # Auto-merge (like Google Docs)
+# strategy: git             # Branch/PR/merge (for code)
+# strategy: lock            # Exclusive access
+# strategy: last-write-wins # Don't care about conflicts
+
+sync: realtime              # or: on-demand, ignore
+```
+
+**Planned commands:**
+
+```bash
+agents drive create <name>
+agents drive list
+agents drive use <name>
+agents drive sync
+agents drive checkpoint "before refactor"
+agents drive rollback <checkpoint>
+```
+
+**Multi-agent coordination:** When multiple agents (or developers) work on the same drive, the drive acts as a coordination layer - checkout files, see who's working on what, avoid conflicts.
+
 ## Related
 
 - [@swarmify/agents-mcp](https://www.npmjs.com/package/@swarmify/agents-mcp) - MCP server for sub-agent spawning

package/dist/index.js

@@ -24,6 +24,7 @@ import { cloneRepo, parseSource } from './lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommand, uninstallCommand, listInstalledCommandsWithScope, promoteCommandToUser, commandExists, commandContentMatches, } from './lib/commands.js';
 import { discoverHooksFromRepo, installHooks, listInstalledHooksWithScope, promoteHookToUser, removeHook, hookExists, hookContentMatches, getSourceHookEntry, } from './lib/hooks.js';
 import { discoverSkillsFromRepo, installSkill, uninstallSkill, listInstalledSkillsWithScope, promoteSkillToUser, getSkillInfo, getSkillRules, skillExists, skillContentMatches, } from './lib/skills.js';
+import { discoverInstructionsFromRepo, resolveInstructionsSource, installInstructions, uninstallInstructions, listInstalledInstructionsWithScope, promoteInstructionsToUser, instructionsExists, instructionsContentMatches, getInstructionsContent, } from './lib/instructions.js';
 import { DEFAULT_REGISTRIES } from './lib/types.js';
 import { search as searchRegistries, getRegistries, setRegistry, removeRegistry, resolvePackage, } from './lib/registry.js';
 const program = new Command();
@@ -179,6 +180,10 @@ program
         agent: AGENTS[agentId],
         mcps: listInstalledMcpsWithScope(agentId, cwd),
     }));
+    const instructionsData = agentsToShow.map((agentId) => ({
+        agent: AGENTS[agentId],
+        instructions: listInstalledInstructionsWithScope(agentId, cwd),
+    }));
     const scopes = filterAgentId ? [] : getScopesByPriority();
     spinner.stop();
     // Helper to format MCP with version
@@ -249,6 +254,23 @@ program
             }
         }
     }
+    console.log(chalk.bold('\nInstalled Instructions\n'));
+    for (const { agent, instructions } of instructionsData) {
+        const userInstr = instructions.find((i) => i.scope === 'user' && i.exists);
+        const projectInstr = instructions.find((i) => i.scope === 'project' && i.exists);
+        if (!userInstr && !projectInstr) {
+            console.log(`  ${chalk.bold(agent.name)}: ${chalk.gray('none')}`);
+        }
+        else {
+            console.log(`  ${chalk.bold(agent.name)}:`);
+            if (userInstr) {
+                console.log(`    ${chalk.gray('User:')} ${chalk.cyan(agent.instructionsFile)}`);
+            }
+            if (projectInstr) {
+                console.log(`    ${chalk.gray('Project:')} ${chalk.yellow(agent.instructionsFile)}`);
+            }
+        }
+    }
     // Only show scopes when not filtering by agent
     if (!filterAgentId) {
         if (scopes.length > 0) {
@@ -364,6 +386,7 @@ program
         const allCommands = discoverCommands(localPath);
         const allSkills = discoverSkillsFromRepo(localPath);
         const discoveredHooks = discoverHooksFromRepo(localPath);
+        const allInstructions = discoverInstructionsFromRepo(localPath);
         // Determine which agents to sync
         const cliStates = await getAllCliStates();
         let selectedAgents;
@@ -506,12 +529,27 @@ program
                 }
             }
         }
+        // Process instructions
+        for (const instr of allInstructions) {
+            if (!selectedAgents.includes(instr.agentId))
+                continue;
+            const hasExisting = instructionsExists(instr.agentId, 'user');
+            if (!hasExisting) {
+                newItems.push({ type: 'instructions', name: AGENTS[instr.agentId].instructionsFile, agents: [instr.agentId], isNew: true });
+            }
+            else if (instructionsContentMatches(instr.agentId, instr.sourcePath, 'user')) {
+                upToDateItems.push({ type: 'instructions', name: AGENTS[instr.agentId].instructionsFile, agents: [instr.agentId], isNew: false });
+            }
+            else {
+                existingItems.push({ type: 'instructions', name: AGENTS[instr.agentId].instructionsFile, agents: [instr.agentId], isNew: false });
+            }
+        }
         // Display overview
         console.log(chalk.bold('\nOverview\n'));
         const formatAgentList = (agents) => agents.map((id) => AGENTS[id].name).join(', ');
         if (newItems.length > 0) {
             console.log(chalk.green('  NEW (will install):\n'));
-            const byType = { command: [], skill: [], hook: [], mcp: [] };
+            const byType = { command: [], skill: [], hook: [], mcp: [], instructions: [] };
             for (const item of newItems)
                 byType[item.type].push(item);
             if (byType.command.length > 0) {
@@ -538,11 +576,17 @@ program
                     console.log(`      ${chalk.cyan(item.name.padEnd(20))} ${chalk.gray(formatAgentList(item.agents))}`);
                 }
             }
+            if (byType.instructions.length > 0) {
+                console.log(`    Instructions:`);
+                for (const item of byType.instructions) {
+                    console.log(`      ${chalk.cyan(item.name.padEnd(20))} ${chalk.gray(formatAgentList(item.agents))}`);
+                }
+            }
             console.log();
         }
         if (upToDateItems.length > 0) {
             console.log(chalk.gray('  UP TO DATE (no changes):\n'));
-            const byType = { command: [], skill: [], hook: [], mcp: [] };
+            const byType = { command: [], skill: [], hook: [], mcp: [], instructions: [] };
             for (const item of upToDateItems)
                 byType[item.type].push(item);
             if (byType.command.length > 0) {
@@ -563,11 +607,17 @@ program
                     console.log(`      ${chalk.dim(item.name.padEnd(20))} ${chalk.dim(formatAgentList(item.agents))}`);
                 }
             }
+            if (byType.instructions.length > 0) {
+                console.log(`    Instructions:`);
+                for (const item of byType.instructions) {
+                    console.log(`      ${chalk.dim(item.name.padEnd(20))} ${chalk.dim(formatAgentList(item.agents))}`);
+                }
+            }
             console.log();
         }
         if (existingItems.length > 0) {
             console.log(chalk.yellow('  EXISTING (conflicts):\n'));
-            const byType = { command: [], skill: [], hook: [], mcp: [] };
+            const byType = { command: [], skill: [], hook: [], mcp: [], instructions: [] };
             for (const item of existingItems)
                 byType[item.type].push(item);
             if (byType.command.length > 0) {
@@ -594,6 +644,12 @@ program
                     console.log(`      ${chalk.yellow(item.name.padEnd(20))} ${chalk.gray(formatAgentList(item.agents))}`);
                 }
             }
+            if (byType.instructions.length > 0) {
+                console.log(`    Instructions:`);
+                for (const item of byType.instructions) {
+                    console.log(`      ${chalk.yellow(item.name.padEnd(20))} ${chalk.gray(formatAgentList(item.agents))}`);
+                }
+            }
             console.log();
         }
         if (newItems.length === 0 && existingItems.length === 0) {
@@ -666,8 +722,8 @@ program
         }
         // Install new items (no conflicts)
         console.log();
-        let installed = { commands: 0, skills: 0, hooks: 0, mcps: 0 };
-        let skipped = { commands: 0, skills: 0, hooks: 0, mcps: 0 };
+        let installed = { commands: 0, skills: 0, hooks: 0, mcps: 0, instructions: 0 };
+        let skipped = { commands: 0, skills: 0, hooks: 0, mcps: 0, instructions: 0 };
         // Install commands
         const cmdSpinner = ora('Installing commands...').start();
         for (const item of [...newItems, ...existingItems].filter((i) => i.type === 'command')) {
@@ -679,8 +735,13 @@ program
             for (const agentId of item.agents) {
                 const sourcePath = resolveCommandSource(localPath, item.name, agentId);
                 if (sourcePath) {
-                    installCommand(sourcePath, agentId, item.name, method);
-                    installed.commands++;
+                    const result = installCommand(sourcePath, agentId, item.name, method);
+                    if (result.error) {
+                        console.log(chalk.yellow(`\n  Warning: ${item.name} (${AGENTS[agentId].name}): ${result.error}`));
+                    }
+                    else {
+                        installed.commands++;
+                    }
                 }
             }
         }
@@ -759,6 +820,39 @@ program
                 mcpSpinner.info('No MCP servers to register');
             }
         }
+        // Install instructions
+        const instructionItems = [...newItems, ...existingItems].filter((i) => i.type === 'instructions');
+        if (instructionItems.length > 0) {
+            const instrSpinner = ora('Installing instructions...').start();
+            for (const item of instructionItems) {
+                const decision = item.isNew ? 'overwrite' : decisions.get(`instructions:${item.name}`);
+                if (decision === 'skip') {
+                    skipped.instructions++;
+                    continue;
+                }
+                for (const agentId of item.agents) {
+                    const sourcePath = resolveInstructionsSource(localPath, agentId);
+                    if (sourcePath) {
+                        const result = installInstructions(sourcePath, agentId, method);
+                        if (result.error) {
+                            console.log(chalk.yellow(`\n  Warning: ${item.name} (${AGENTS[agentId].name}): ${result.error}`));
+                        }
+                        else {
+                            installed.instructions++;
+                        }
+                    }
+                }
+            }
+            if (skipped.instructions > 0) {
+                instrSpinner.succeed(`Installed ${installed.instructions} instructions (skipped ${skipped.instructions})`);
+            }
+            else if (installed.instructions > 0) {
+                instrSpinner.succeed(`Installed ${installed.instructions} instructions`);
+            }
+            else {
+                instrSpinner.info('No instructions to install');
+            }
+        }
         // Sync CLI versions (user scope only)
         if (isUserScope && !options.skipClis && manifest?.clis) {
             const cliSpinner = ora('Checking CLI versions...').start();
@@ -852,6 +946,44 @@ program
             exported++;
         }
     }
+    // Export MCP servers from installed agents
+    console.log();
+    let mcpExported = 0;
+    const mcpByName = new Map();
+    for (const agentId of MCP_CAPABLE_AGENTS) {
+        if (!cliStates[agentId]?.installed)
+            continue;
+        const mcps = listInstalledMcpsWithScope(agentId);
+        for (const mcp of mcps) {
+            if (mcp.scope !== 'user')
+                continue; // Only export user-scoped MCPs
+            const existing = mcpByName.get(mcp.name);
+            if (existing) {
+                if (!existing.agents.includes(agentId)) {
+                    existing.agents.push(agentId);
+                }
+            }
+            else {
+                mcpByName.set(mcp.name, {
+                    command: mcp.command || '',
+                    agents: [agentId],
+                });
+            }
+        }
+    }
+    if (mcpByName.size > 0) {
+        manifest.mcp = manifest.mcp || {};
+        for (const [name, config] of mcpByName) {
+            manifest.mcp[name] = {
+                command: config.command,
+                transport: 'stdio',
+                agents: config.agents,
+                scope: 'user',
+            };
+            console.log(`  ${chalk.green('+')} MCP: ${name} (${config.agents.map(id => AGENTS[id].name).join(', ')})`);
+            mcpExported++;
+        }
+    }
     if (!options.exportOnly) {
         writeManifest(localPath, manifest);
         console.log(chalk.bold(`\nUpdated ${MANIFEST_FILENAME}`));
@@ -952,8 +1084,13 @@ commandsCmd
                     continue;
                 const sourcePath = resolveCommandSource(localPath, command.name, agentId);
                 if (sourcePath) {
-                    installCommand(sourcePath, agentId, command.name, 'symlink');
-                    console.log(`    ${chalk.green('+')} ${AGENTS[agentId].name}`);
+                    const result = installCommand(sourcePath, agentId, command.name, 'symlink');
+                    if (result.error) {
+                        console.log(`    ${chalk.yellow('!')} ${AGENTS[agentId].name}: ${result.error}`);
+                    }
+                    else {
+                        console.log(`    ${chalk.green('+')} ${AGENTS[agentId].name}`);
+                    }
                 }
             }
         }
@@ -1427,6 +1564,152 @@ skillsCmd
     }
 });
 // =============================================================================
+// INSTRUCTIONS COMMANDS
+// =============================================================================
+const instructionsCmd = program
+    .command('instructions')
+    .alias('instr')
+    .description('Manage agent instructions (CLAUDE.md, GEMINI.md, etc.)');
+instructionsCmd
+    .command('list')
+    .description('List installed instructions files')
+    .option('-a, --agent <agent>', 'Filter by agent')
+    .action(async (options) => {
+    const cwd = process.cwd();
+    const agents = options.agent
+        ? [resolveAgentName(options.agent)].filter(Boolean)
+        : ALL_AGENT_IDS;
+    console.log(chalk.bold('Installed Instructions\n'));
+    for (const agentId of agents) {
+        const agent = AGENTS[agentId];
+        const installed = listInstalledInstructionsWithScope(agentId, cwd);
+        const userInstr = installed.find((i) => i.scope === 'user');
+        const projectInstr = installed.find((i) => i.scope === 'project');
+        const userStatus = userInstr?.exists ? chalk.green(agent.instructionsFile) : chalk.gray('none');
+        const projectStatus = projectInstr?.exists ? chalk.yellow(agent.instructionsFile) : chalk.gray('none');
+        console.log(`  ${chalk.bold(agent.name)}:`);
+        console.log(`    ${chalk.gray('User:')} ${userStatus}`);
+        console.log(`    ${chalk.gray('Project:')} ${projectStatus}`);
+        console.log();
+    }
+});
+instructionsCmd
+    .command('view [agent]')
+    .alias('show')
+    .description('View instructions content for an agent')
+    .option('-s, --scope <scope>', 'Scope: user or project', 'user')
+    .action(async (agentArg, options) => {
+    const cwd = process.cwd();
+    let agentId;
+    if (agentArg) {
+        agentId = resolveAgentName(agentArg) || undefined;
+        if (!agentId) {
+            console.log(chalk.red(`Unknown agent: ${agentArg}`));
+            process.exit(1);
+        }
+    }
+    else {
+        const choices = ALL_AGENT_IDS.filter((id) => instructionsExists(id, 'user', cwd) || instructionsExists(id, 'project', cwd));
+        if (choices.length === 0) {
+            console.log(chalk.yellow('No instructions files found.'));
+            return;
+        }
+        agentId = await select({
+            message: 'Select agent:',
+            choices: choices.map((id) => ({ name: AGENTS[id].name, value: id })),
+        });
+    }
+    const scope = (options?.scope || 'user');
+    const content = getInstructionsContent(agentId, scope, cwd);
+    if (!content) {
+        console.log(chalk.yellow(`No ${scope} instructions found for ${AGENTS[agentId].name}`));
+        return;
+    }
+    console.log(chalk.bold(`\n${AGENTS[agentId].name} Instructions (${scope}):\n`));
+    console.log(content);
+});
+instructionsCmd
+    .command('diff [agent]')
+    .description('Show differences between local and repo instructions')
+    .action(async (agentArg) => {
+    const cwd = process.cwd();
+    const meta = readState();
+    const scopes = getScopesByPriority();
+    if (scopes.length === 0) {
+        console.log(chalk.yellow('No repo configured. Run: agents repo add <source>'));
+        return;
+    }
+    const agents = agentArg
+        ? [resolveAgentName(agentArg)].filter(Boolean)
+        : ALL_AGENT_IDS;
+    const diff = await import('diff');
+    for (const { name: scopeName, config } of scopes) {
+        const localPath = getRepoLocalPath(config.source);
+        const repoInstructions = discoverInstructionsFromRepo(localPath);
+        for (const agentId of agents) {
+            const repoInstr = repoInstructions.find((i) => i.agentId === agentId);
+            if (!repoInstr)
+                continue;
+            const installedContent = getInstructionsContent(agentId, 'user', cwd);
+            if (!installedContent) {
+                console.log(`${chalk.bold(AGENTS[agentId].name)}: ${chalk.green('NEW')} (not installed)`);
+                continue;
+            }
+            const repoContent = fs.readFileSync(repoInstr.sourcePath, 'utf-8');
+            if (installedContent.trim() === repoContent.trim()) {
+                console.log(`${chalk.bold(AGENTS[agentId].name)}: ${chalk.gray('up to date')}`);
+                continue;
+            }
+            console.log(`${chalk.bold(AGENTS[agentId].name)}:`);
+            const changes = diff.diffLines(installedContent, repoContent);
+            for (const change of changes) {
+                if (change.added) {
+                    process.stdout.write(chalk.green(change.value));
+                }
+                else if (change.removed) {
+                    process.stdout.write(chalk.red(change.value));
+                }
+            }
+            console.log();
+        }
+    }
+});
+instructionsCmd
+    .command('push <agent>')
+    .description('Save project-scoped instructions to user scope')
+    .action((agentArg) => {
+    const cwd = process.cwd();
+    const agentId = resolveAgentName(agentArg);
+    if (!agentId) {
+        console.log(chalk.red(`Unknown agent: ${agentArg}`));
+        process.exit(1);
+    }
+    const result = promoteInstructionsToUser(agentId, cwd);
+    if (result.success) {
+        console.log(chalk.green(`Pushed ${AGENTS[agentId].instructionsFile} to user scope`));
+    }
+    else {
+        console.log(chalk.red(result.error || 'Failed to push instructions'));
+    }
+});
+instructionsCmd
+    .command('remove <agent>')
+    .description('Remove user-scoped instructions for an agent')
+    .action((agentArg) => {
+    const agentId = resolveAgentName(agentArg);
+    if (!agentId) {
+        console.log(chalk.red(`Unknown agent: ${agentArg}`));
+        process.exit(1);
+    }
+    const result = uninstallInstructions(agentId);
+    if (result) {
+        console.log(chalk.green(`Removed ${AGENTS[agentId].instructionsFile}`));
+    }
+    else {
+        console.log(chalk.yellow(`No instructions file found for ${AGENTS[agentId].name}`));
+    }
+});
+// =============================================================================
 // MCP COMMANDS
 // =============================================================================
 const mcpCmd = program
@@ -2300,18 +2583,29 @@ program
             if (hasCommands) {
                 console.log(chalk.bold('\nInstalling commands...'));
                 let installed = 0;
+                let failed = 0;
                 for (const command of commands) {
                     for (const agentId of agents) {
                         if (!gitCliStates[agentId]?.installed && agentId !== 'cursor')
                             continue;
                         const sourcePath = resolveCommandSource(localPath, command.name, agentId);
                         if (sourcePath) {
-                            installCommand(sourcePath, agentId, command.name, 'symlink');
-                            installed++;
+                            const result = installCommand(sourcePath, agentId, command.name, 'symlink');
+                            if (result.error) {
+                                failed++;
+                            }
+                            else {
+                                installed++;
+                            }
                         }
                     }
                 }
-                console.log(`  Installed ${installed} command instances`);
+                if (failed > 0) {
+                    console.log(`  Installed ${installed} command instances (${failed} failed)`);
+                }
+                else {
+                    console.log(`  Installed ${installed} command instances`);
+                }
             }
             // Install skills
             if (hasSkills) {