@swarmify/agents-cli 1.3.13 → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## 1.5.0
+
+**Pull command redesign**
+
+- Agent-specific sync: `agents pull claude` syncs only Claude resources
+- Agent aliases: `cc`, `cx`, `gx`, `cr`, `oc` for quick filtering
+- Overview display: Shows NEW vs EXISTING resources before installation
+- Per-resource prompts: Choose overwrite/skip/cancel for each conflict
+- `-y` flag: Auto-confirm and skip conflicts
+- `-f` flag: Auto-confirm and overwrite conflicts
+- Graceful cancellation: Ctrl+C shows "Cancelled" cleanly
+
+## 1.4.0
+
+- Conflict detection for pull command
+- Bulk conflict handling (overwrite all / skip all / cancel)
+
+## 1.3.13
+
+- Enabled skills support for Cursor and OpenCode
+- Fixed Cursor MCP config path (now uses mcp.json)
+
+## 1.3.12
+
+- Fixed MCP detection for Codex (TOML config format)
+- Fixed MCP detection for OpenCode (JSONC config format)
+- Added smol-toml dependency for TOML parsing
+
+## 1.3.11
+
+- Status command shows resource names instead of counts
+- Better formatting for installed commands, skills, and MCPs
+
+## 1.3.0
+
+- Added Agent Skills support (SKILL.md + rules/)
+- Skills validation with metadata requirements
+- Central skills directory at ~/.agents/skills/
+
+## 1.2.0
+
+- Added hooks support for Claude and Gemini
+- Hook discovery from shared/ and agent-specific directories
+- Project-scope hooks support
+
+## 1.1.0
+
+- Added MCP server registration
+- Support for stdio and http transports
+- Per-agent MCP configuration
+
+## 1.0.0
+
+- Initial release
+- Pull/push commands for syncing agent configurations
+- Slash command management
+- Multi-agent support (Claude, Codex, Gemini, Cursor, OpenCode)

package/README.md

@@ -1,21 +1,25 @@
 # @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
+
+One command to configure all your agents.
 
 ```bash
-# Pull your config on a new machine
-agents pull gh:username/.agents
+# New machine? One command.
+agents pull
 
-# See what you have installed
-agents status claude
+# See what's installed
+agents status
 ```
 
 ```
@@ -40,145 +44,188 @@ 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. Pull (auto-configures from default repo on first run)
+agents pull
 
-# Remove
-agents commands remove my-command
+# 3. Check what's installed
+agents status
 ```
 
-### MCP Servers
+Pull a specific agent only:
 
 ```bash
-# List servers across all agents
-agents mcp list
+agents pull claude    # Only configure Claude Code
+agents pull codex     # Only configure Codex
+```
 
-# 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
+## Using Your Own Config
 
-# Add HTTP server with headers
-agents mcp add api https://api.example.com/mcp --transport http -H "Authorization:Bearer token"
+By default, `agents pull` uses the [system repo](https://github.com/muqsitnawaz/.agents). To use your own:
 
-# Remove from all agents
-agents mcp remove swarm
-```
+```bash
+# Fork the system repo, then:
+agents repo add gh:username/.agents
 
-### Hooks
+# Now pull uses your repo
+agents pull
+```
 
-```bash
-# List hooks
-agents hooks list
+## .agents Repo Structure
 
-# Install from repo
-agents hooks add gh:user/my-hooks
+```
+.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/)
+```
 
-# Remove
-agents hooks remove my-hook
+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]
 ```
 
-### Skills
+## Commands
 
-Agent Skills are reusable capabilities (SKILL.md + rules/) that agents can invoke.
+### Status
 
 ```bash
-# List installed skills
-agents skills list
-
-# Install from repo
-agents skills add gh:user/my-skills
-
-# Show details
-agents skills info my-skill
+agents status              # Full overview
+agents status --agent claude
 ```
 
-### Search & Install from Registries
-
-Search public registries for MCP servers and skills:
+### Pull & Push
 
 ```bash
-# Search all registries
-agents search github
-agents search filesystem --limit 10
+agents pull                # Sync all agents from your repo
+agents pull claude         # Sync only Claude resources
+agents pull cc             # Same (aliases: cc, codex/cx, gemini/gx)
+agents pull --dry-run      # Preview what would change
+agents pull -y             # Auto-confirm, skip conflicts
+agents pull -f             # Auto-confirm, overwrite conflicts
+agents push                # Push local changes back
+```
 
-# Filter by type
-agents search github --type mcp
+The pull command shows an overview of NEW vs EXISTING resources before installation. For conflicts, you're prompted per-resource to overwrite, skip, or cancel.
 
-# Install from registry (auto-detected)
-agents add mcp:io.github.bytedance/mcp-server-filesystem
+### Slash Commands
 
-# Or use identifiers
-agents add skill:user/my-skill    # Skill from git
-agents add gh:user/my-repo        # Git repo directly
+```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
 ```
 
-### Registry Management
+### MCP Servers
 
 ```bash
-# List configured registries
-agents registry list
-
-# Add custom registry
-agents registry add mcp myregistry https://api.example.com/v1
+# List across all agents
+agents mcp list
 
-# Configure API key
-agents registry config mcp myregistry --api-key YOUR_KEY
+# 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
 
-# Disable/enable
-agents registry disable mcp myregistry
-agents registry enable mcp myregistry
+# Search registries
+agents search filesystem
+agents add mcp:@anthropic-ai/mcp-filesystem
 
 # Remove
-agents registry remove mcp myregistry
+agents mcp remove memory
 ```
 
-Default registries:
-- `official` (MCP): https://registry.modelcontextprotocol.io
-
-### Sync
+### Skills
 
 ```bash
-# Pull config from your .agents repo
-agents pull gh:username/.agents
+agents skills list
+agents skills add gh:user/my-skills
+agents skills info my-skill
+```
 
-# Push local changes back
-agents push
+### Hooks
 
-# Full status
-agents status
+```bash
+agents hooks list
+agents hooks add gh:user/my-hooks
+agents hooks remove my-hook
 ```
 
 ### CLI Management
 
 ```bash
-# Show installed versions
-agents cli list
+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
+```
+
+## Scopes
 
-# Upgrade all to latest
-agents cli upgrade --latest
+Resources can exist at two levels:
+
+| Scope | Location | Use |
+|-------|----------|-----|
+| User | `~/.{agent}/` | Available everywhere |
+| Project | `./.{agent}/` | This repo only, committed |
+
+Promote project-scoped items to user scope:
+
+```bash
+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 +233,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 |
-
-## Your .agents Repo
+| Gemini CLI | Yes | Yes | Yes | Yes |
+| Cursor | Yes | Yes | - | - |
+| OpenCode | Yes | Yes | - | - |
 
-```
-.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