@swarmify/agents-cli 1.0.0 → 1.2.0

package/README.md

@@ -1,145 +1,165 @@
 # @swarmify/agents-cli
 
-Dotfiles manager for AI coding agents. Sync skills, MCP servers, and CLI versions across machines.
-
-Part of the [Swarmify](https://github.com/muqsitnawaz/swarmify) multi-agent toolkit.
-
-## Install
+Dotfiles for AI coding agents. Sync prompts, MCP servers, hooks, and skills across Claude, Codex, Gemini, Cursor, and more.
 
 ```bash
 npm install -g @swarmify/agents-cli
 ```
 
-## Quick Start
+## The Idea
+
+You configure Claude Code manually. Then you switch to Codex or Gemini and start from scratch. This CLI syncs your setup across all agents:
 
 ```bash
-# See what's installed
+# See what you have installed
 agents status
 
-# Sync from your .agents repo
+# Pull your config on a new machine
 agents pull gh:username/.agents
-
-# Or use a local directory
-agents pull ~/dotfiles/.agents
 ```
 
+## What Gets Synced
+
+| 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 |
+
 ## Commands
 
-### Status & Sync
+### Prompts (Slash Commands)
 
-| Command | Description |
-|---------|-------------|
-| `agents status` | Show CLIs, skills, sync source |
-| `agents pull <source>` | Pull and install from repo |
-| `agents push` | Export local config to repo |
-| `agents sync <source>` | Alias for pull |
+```bash
+# List what's installed
+agents commands list
 
-### Skills
+# Install from a git repo
+agents commands add gh:user/my-prompts
 
-| Command | Description |
-|---------|-------------|
-| `agents skills list` | List installed skills |
-| `agents skills list --agent claude` | Filter by agent |
-| `agents skills add gh:user/skills` | Install from git repo |
-| `agents skills remove <name>` | Uninstall skill |
+# Remove
+agents commands remove my-command
+```
 
 ### MCP Servers
 
-| Command | Description |
-|---------|-------------|
-| `agents mcp list` | Show registration status |
-| `agents mcp add <name> <command>` | Add to manifest |
-| `agents mcp remove <name>` | Unregister from agents |
-| `agents mcp register` | Register all from manifest |
+```bash
+# List servers across all agents
+agents mcp list
 
-### CLI Management
+# 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
 
-| Command | Description |
-|---------|-------------|
-| `agents cli list` | Show versions and paths |
-| `agents cli add <agent>` | Add to manifest |
-| `agents cli remove <agent>` | Remove from manifest |
-| `agents cli upgrade` | Upgrade all to manifest versions |
-| `agents cli upgrade --latest` | Upgrade to latest |
+# Add HTTP server with headers
+agents mcp add api https://api.example.com/mcp --transport http -H "Authorization:Bearer token"
 
-## Repo Structure
+# Remove from all agents
+agents mcp remove swarm
+```
 
-Your `.agents` repo should look like:
+### Hooks
 
+```bash
+# List hooks
+agents hooks list
+
+# Install from repo
+agents hooks add gh:user/my-hooks
+
+# Remove
+agents hooks remove my-hook
 ```
-.agents/
-  agents.yaml           # Manifest with CLIs, MCP, defaults
-  shared/
-    commands/           # Skills shared across all agents
-  claude/
-    commands/           # Claude-specific skills
-    hooks/              # Claude hooks
-  codex/
-    prompts/            # Codex-specific skills
-  gemini/
-    prompts/            # Gemini skills (TOML format)
+
+### 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
 ```
 
-## Manifest Format
-
-```yaml
-clis:
-  claude:
-    package: "@anthropic-ai/claude-code"
-    version: "2.0.65"
-  codex:
-    package: "@openai/codex"
-    version: "0.88.0"
-
-mcp:
-  swarm:
-    command: "npx @swarmify/agents-mcp"
-    transport: stdio
-    scope: user
-    agents: [claude, codex]
-
-defaults:
-  method: symlink
-  scope: global
-  agents: [claude, codex, gemini]
+### Sync
+
+```bash
+# Pull config from your .agents repo
+agents pull gh:username/.agents
+
+# Push local changes back
+agents push
+
+# Full status
+agents status
 ```
 
-## Supported Agents
+### CLI Management
 
-| Agent | CLI | Config Directory |
-|-------|-----|------------------|
-| Claude | `claude` | `~/.claude/` |
-| Codex | `codex` | `~/.codex/` |
-| Gemini | `gemini` | `~/.gemini/` |
-| Cursor | `cursor-agent` | `~/.cursor-agent/` |
-| OpenCode | `opencode` | `~/.opencode/` |
-| Trae | `trae-cli` | `~/.trae/` |
+```bash
+# Show installed versions
+agents cli list
 
-## Options
+# Upgrade all to latest
+agents cli upgrade --latest
+```
 
-| Flag | Description |
-|------|-------------|
-| `-y, --yes` | Skip interactive prompts |
-| `-f, --force` | Force overwrite |
-| `--dry-run` | Preview changes |
-| `--skip-mcp` | Skip MCP registration |
+## Filtering
 
-## State
+All commands support `--agent` and `--scope` filters:
 
-Local state is stored in `~/.agents/`:
+```bash
+agents commands list --agent claude
+agents mcp list --scope project
+agents skills list --agent codex --scope user
+```
 
+## Scopes
+
+| Scope | Location | Use Case |
+|-------|----------|----------|
+| User | `~/.{agent}/` | Available everywhere |
+| Project | `./.{agent}/` | This repo only |
+
+Promote project-scoped items to user scope:
+
+```bash
+agents commands push my-command
+agents mcp push my-server
 ```
-~/.agents/
-  state.json    # Sync state, last sync time
-  repos/        # Cloned .agents repos
-  packages/     # External skill packages
+
+## Supported Agents
+
+| Agent | Prompts | MCP | Hooks | Skills |
+|-------|---------|-----|-------|--------|
+| Claude Code | Yes | Yes | Yes | Yes |
+| Codex | Yes | Yes | - | Yes |
+| Gemini CLI | Yes (TOML) | Yes | Yes | Yes |
+| Cursor | Yes | - | - | - |
+| OpenCode | Yes | - | - | - |
+| Trae | 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
 ```
 
-## Related Packages
+## Related
 
-| Package | Description |
-|---------|-------------|
-| [@swarmify/agents-mcp](https://www.npmjs.com/package/@swarmify/agents-mcp) | MCP server for multi-agent orchestration. Spawn Claude, Codex, Gemini agents in parallel. |
+- [@swarmify/agents-mcp](https://www.npmjs.com/package/@swarmify/agents-mcp) - Multi-agent orchestration MCP server
 
 ## License