@swarmify/agents-cli 1.6.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +59 -319
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,372 +1,112 @@
1
1
  # agents
2
2
 
3
- **One CLI for every AI coding agent.** Version manager, config sync, package manager, and automation daemon for Claude, Codex, Gemini CLI, Cursor, and OpenCode.
4
-
5
- [![npm](https://img.shields.io/npm/v/@swarmify/agents-cli)](https://www.npmjs.com/package/@swarmify/agents-cli) [![license](https://img.shields.io/npm/l/@swarmify/agents-cli)](LICENSE) [![node](https://img.shields.io/node/v/@swarmify/agents-cli)](package.json)
6
-
7
- ```bash
8
- npm install -g @swarmify/agents-cli
9
- ```
10
-
11
- [Quick Start](#quick-start) | [Why](#why) | [Version Control](#version-control) | [Config Sync](#config-sync) | [Package Management](#package-management) | [MCP Servers](#mcp-servers) | [Skills & Commands](#skills--commands) | [Jobs & Sandboxing](#jobs--sandboxing) | [Compatibility](#compatibility) | [All Commands](#all-commands)
12
-
13
- ---
14
-
15
- ## Quick Start
3
+ **One CLI for all your AI coding agents.**
16
4
 
17
5
  ```bash
18
6
  npm install -g @swarmify/agents-cli
19
- agents pull # Syncs config from default repo on first run
20
- agents status # Shows what got installed
21
- ```
22
-
23
- Point it at your own config repo:
24
-
25
- ```bash
26
- agents repo add gh:yourname/.agents
27
- agents pull
28
- ```
29
-
30
- > Also available as `ag` -- every command above works with `ag pull`, `ag status`, etc.
31
-
32
- ## Why
33
-
34
- Every agent works differently. Installing an MCP server in Claude is `claude mcp add`. In Codex it's `codex mcp add` with different flags. In OpenCode it's interactive. Gemini wants a config file edit. Skills, commands, memory files -- same story, different formats, different locations, different procedures for each agent.
35
-
36
- If you use more than one agent, you're doing everything N times. New machine? Do it all again. Teammate wants your setup? Good luck explaining five different config systems.
37
-
38
- `agents` is one CLI that handles all of it:
39
-
40
- - **Version manager** -- install, pin, and switch agent CLI versions per project, like `nvm` for Node
41
- - **Config sync** -- back up commands, skills, MCPs, memory files, and hooks to a single Git repo. `agents pull` on a new machine and everything is configured across every agent
42
- - **Package manager** -- `agents search notion` finds MCP servers across registries, `agents install mcp:com.notion/mcp` installs and registers it with every agent in one step
43
- - **Automation daemon** -- schedule agents to run on cron with sandboxed permissions, like `systemctl` for AI agents
44
-
45
- ## Version Control
46
-
47
- Install, pin, and switch between agent CLI versions -- like `nvm` for Node.js.
48
-
49
- ```bash
50
- agents add claude@1.5.0 # Install a specific version
51
- agents add claude@latest # Install the latest
52
- agents add claude@1.5.0 -p # Install and pin to this project
53
- agents use claude@1.5.0 # Set global default
54
- agents use claude@1.5.0 -p # Pin version in project manifest
55
- agents list # Show all installed versions
56
- agents list claude # Show versions for one agent
57
- agents remove claude@1.5.0 # Remove a specific version
58
- agents remove claude # Remove all versions
59
- ```
60
-
61
- Per-project pinning lives in `.agents/agents.yaml`:
62
-
63
- ```yaml
64
- agents:
65
- claude: "1.5.0"
66
- codex: "0.1.2"
67
- gemini: latest
68
- ```
69
-
70
- When a shim is in your PATH, running `claude` resolves to the version pinned in the nearest `.agents/agents.yaml`, falling back to the global default.
71
-
72
- <details>
73
- <summary>How version isolation works</summary>
74
-
75
- Each version is installed to `~/.agents/versions/{agent}/{version}/` with its own isolated HOME at `~/.agents/versions/{agent}/{version}/home/`. Shims in `~/.agents/shims/` set HOME and delegate to the correct binary. The isolated HOME symlinks everything from your real HOME except agent config directories (`.claude`, `.codex`, `.gemini`, `.cursor`, `.opencode`, `.agents`), so auth tokens stay per-version while your filesystem remains intact.
76
-
77
- </details>
78
-
79
- ## Config Sync
80
-
81
- A `.agents` repo holds your entire multi-agent configuration. `pull` distributes it; `push` exports local changes back.
82
-
83
- ```bash
84
- agents pull # Sync everything
85
- agents pull claude # Sync one agent
86
- agents push # Export local config to your repo
87
- ```
88
-
89
- Repo structure:
90
-
91
- ```
92
- .agents/
93
- agents.yaml # Pinned versions + defaults
94
- commands/ # Slash commands (*.md)
95
- skills/ # Skills (SKILL.md + rules/)
96
- hooks/ # Hook scripts
97
- memory/ # Memory files (*.md)
98
- mcp/ # MCP server configs (*.yaml)
99
- permissions/
100
- groups/ # Permission groups (*.yaml)
101
7
  ```
102
8
 
103
- Resources exist at two scopes:
9
+ ## The Problem
104
10
 
105
- | Scope | Location | When to use |
106
- |-------|----------|-------------|
107
- | **User** | `~/.{agent}/` | Available everywhere |
108
- | **Project** | `./.{agent}/` | Committed to a specific repo |
11
+ You use Claude, Codex, Gemini, Cursor. Each has its own:
12
+ - Config location (`~/.claude/`, `~/.codex/`, `~/.gemini/`...)
13
+ - MCP registration (`claude mcp add` vs `codex mcp add` vs config file edits)
14
+ - Command format (markdown vs TOML)
15
+ - Version management (none)
109
16
 
110
- Use `add` subcommands to install resources from repos or local paths (`agents commands add`, `agents skills add`, etc.).
17
+ New machine? Redo everything. Teammate wants your setup? Good luck.
111
18
 
112
- ## Package Management
113
-
114
- Search and install MCP servers and skills like `apt` or `brew`. Registries are searched automatically.
115
-
116
- ```bash
117
- agents search notion
118
- ```
119
-
120
- ```
121
- Found 3 packages
122
-
123
- MCP Servers
124
- ai.smithery/smithery-notion - A Notion workspace is a collaborative environment...
125
- Registry: official Install: agents install mcp:ai.smithery/smithery-notion
126
- com.notion/mcp - Official Notion MCP server
127
- Registry: official Install: agents install mcp:com.notion/mcp
128
- ```
129
-
130
- Install with one command -- the server gets registered with every agent automatically:
19
+ ## The Solution
131
20
 
132
21
  ```bash
133
- agents install mcp:com.notion/mcp # MCP server from registry
134
- agents install skill:muqsitnawaz/mq # Skill from GitHub
135
- agents install gh:user/repo # Any .agents-compatible repo
22
+ agents pull gh:yourname/.agents # One command. Every agent configured.
136
23
  ```
137
24
 
138
- Identifier prefixes:
25
+ That's it. Your MCP servers, commands, skills, memory files, and permissions - synced to Claude, Codex, Gemini, Cursor, and OpenCode in one step.
139
26
 
140
- | Prefix | What it installs | Source |
141
- |--------|------------------|--------|
142
- | `mcp:` | MCP server | Registry lookup, then `npx`/`uvx` |
143
- | `skill:` | Skill (SKILL.md + rules/) | GitHub repo |
144
- | `gh:` | Full package (skills, commands, MCPs) | GitHub repo |
27
+ ---
145
28
 
146
- ## MCP Servers
29
+ ## What You Can Do
147
30
 
148
- Search registries, install servers, and register them with every agent in one step.
31
+ ### Install MCP servers everywhere at once
149
32
 
150
33
  ```bash
151
- agents search filesystem # Search MCP registries
152
- agents install mcp:filesystem # Install and register with all agents
153
- agents mcp add myserver npx ... # Add a custom MCP server
154
- agents mcp list # Show servers and registration status
155
- agents mcp register # Register all servers with agent CLIs
156
- agents mcp remove myserver # Remove from all agents
157
- ```
158
-
159
- MCP servers are stored as YAML in `~/.agents/mcp/`:
160
-
161
- ```yaml
162
- # ~/.agents/mcp/Swarm.yaml
163
- name: Swarm
164
- transport: stdio
165
- command: npx
166
- args:
167
- - -y
168
- - '@swarmify/agents-mcp@latest'
169
- ```
170
-
171
- During `agents use` or `agents pull`, you select which MCPs to sync to each agent version.
172
-
173
- ## Permissions
174
-
175
- Permissions are organized into groups in `~/.agents/permissions/groups/`. Each group contains related permission rules:
176
-
177
- ```
178
- permissions/groups/
179
- 00-header.yaml # Metadata
180
- 01-core.yaml # Core shell utilities
181
- 02-node.yaml # Node.js ecosystem (60 rules)
182
- 03-python.yaml # Python ecosystem (47 rules)
183
- 04-go.yaml # Go ecosystem
184
- ...
185
- 20-webfetch-dev.yaml # WebFetch for dev docs
186
- 30-paths.yaml # File system paths
187
- 99-deny.yaml # Explicit denials
188
- ```
189
-
190
- During `agents use`, you can select which groups to sync:
191
-
192
- ```
193
- ? Which resources from ~/.agents/ would you like to sync?
194
- Commands (21 available), Skills (7 available), MCPs (1 available),
195
- Permissions (19 groups, 3132 rules)
34
+ agents search notion # Find MCP servers
35
+ agents install mcp:com.notion/mcp # Install + register with ALL agents
196
36
  ```
197
37
 
198
- Permission groups are combined and applied to each agent's native format:
199
- - **Claude**: `~/.claude/settings.json` (`permissions.allow/deny`)
200
- - **Codex**: `~/.codex/config.toml` (`approval_policy`, `sandbox_mode`)
201
- - **OpenCode**: `~/.opencode/opencode.jsonc` (`permission.bash`)
202
-
203
- ## Skills & Commands
204
-
205
- ### Slash Commands
38
+ No more running `claude mcp add`, then `codex mcp add`, then editing Gemini's config file.
206
39
 
207
- Slash commands are markdown (or TOML for Gemini) files that appear in the agent's command palette.
40
+ ### Version-lock agents per project
208
41
 
209
42
  ```bash
210
- agents commands list # List installed commands
211
- agents commands add <source> # Install from a repo or local path
212
- agents commands view <name> # Show command contents
213
- agents commands remove <name> # Remove a command
43
+ agents add claude@2.0.0 # Install specific version
44
+ agents use claude@2.0.0 -p # Pin to this project
214
45
  ```
215
46
 
216
- Commands in `commands/` are distributed to every agent. Markdown commands are auto-converted to TOML when installed for Gemini.
47
+ Like `nvm` for Node - different projects can use different agent versions.
217
48
 
218
- ### Skills
219
-
220
- Skills bundle a `SKILL.md` file with optional `rules/` for deeper agent guidance.
49
+ ### Sync your entire setup
221
50
 
222
51
  ```bash
223
- agents skills list # List installed skills
224
- agents skills add <source> # Install from a repo or local path
225
- agents skills view <name> # Show skill contents
226
- agents skills remove <name> # Remove a skill
52
+ agents push # Export your config to git
53
+ agents pull # Restore on any machine
227
54
  ```
228
55
 
229
- ## Cron Jobs & Sandboxing
230
-
231
- Schedule agents to run autonomously on cron. Define a job in YAML or inline, and the daemon handles execution.
232
-
233
- ```yaml
234
- name: daily-pr-digest
235
- schedule: "0 9 * * 1-5"
236
- agent: claude
237
- mode: plan
238
- timeout: 15m
239
- timezone: America/Los_Angeles
240
- prompt: |
241
- Today is {date}. Review all PRs I merged since 5 PM yesterday
242
- across every repo in ~/src/. Summarize what shipped, flag
243
- anything that looks risky, and write the digest to the report.
244
-
245
- variables:
246
- repo_path: ~/src
247
-
248
- allow:
249
- tools: [bash, read, glob, grep]
250
- dirs: [~/src]
56
+ Your `~/.agents/` repo holds commands, skills, MCPs, memory files, hooks, and permissions. One `pull` configures everything.
251
57
 
252
- config:
253
- model: claude-sonnet-4-5
254
- ```
58
+ ### Schedule agents on cron
255
59
 
256
60
  ```bash
257
- # Add jobs from YAML or inline
258
- agents cron add job.yaml # From YAML file
259
- agents cron add my-job -s "0 9 * * *" -a claude -p "..." # Inline with flags
260
- agents cron add reminder --at "14:30" -a claude -p "..." # One-shot job
261
-
262
- # Manage jobs (all commands show picker when name omitted)
263
- agents cron list # Show all jobs and status
264
- agents cron view # View job config (interactive picker)
265
- agents cron edit # Edit in $EDITOR (interactive picker)
266
- agents cron remove # Remove a job (interactive picker)
267
-
268
- # Run and monitor
269
- agents cron run # Run immediately (interactive picker)
270
- agents cron runs # Show execution history
271
- agents cron logs # Show output from latest run
272
- agents cron report # Show report from latest run
273
-
274
- # Enable/disable
275
- agents cron pause # Pause a job (shows only enabled jobs)
276
- agents cron resume # Resume a job (shows only paused jobs)
277
-
278
- # Daemon
279
- agents daemon start # Start the cron scheduler
280
- agents daemon stop # Stop the daemon
281
- agents daemon status # Check daemon status
61
+ agents cron add daily-digest -s "0 9 * * *" -a claude -p "Review yesterday's PRs..."
62
+ agents daemon start
282
63
  ```
283
64
 
284
- Template variables: `{day}`, `{date}`, `{time}`, `{job_name}`, `{last_report}`, plus custom `variables`.
65
+ Agents run sandboxed - they only see directories and tools you explicitly allow.
285
66
 
286
- ## Unified Execution
67
+ ---
287
68
 
288
- Run any agent with a consistent interface using `agents exec`:
69
+ ## Quick Reference
289
70
 
290
71
  ```bash
291
- agents exec claude "Review this PR" # Default mode (plan)
292
- agents exec codex "Fix the bug" --mode edit # Edit mode
293
- agents exec gemini "Analyze code" --effort fast # Fast model
294
- agents exec claude@2.0.0 "Task" --cwd ./project # Specific version + cwd
295
- ```
72
+ # Versions
73
+ agents add claude@latest # Install
74
+ agents use claude@2.0.0 # Set default
75
+ agents list # Show installed
296
76
 
297
- Options:
298
- - `--mode <plan|edit>` - Read-only analysis or allow edits
299
- - `--effort <fast|default|detailed>` - Model selection (maps to haiku/sonnet/opus, etc.)
300
- - `--model <model>` - Override model directly
301
- - `--cwd <dir>` - Working directory
302
- - `--add-dir <dir>` - Add directory access (Claude only, repeatable)
77
+ # Packages
78
+ agents search <query> # Find MCP servers/skills
79
+ agents install mcp:<name> # Install MCP server
80
+ agents install skill:<name> # Install skill
303
81
 
304
- ### Sandbox Isolation
82
+ # Sync
83
+ agents pull # Sync from your repo
84
+ agents push # Push changes back
305
85
 
306
- Each job runs in an isolated environment. The agent never sees your real HOME -- it gets an overlay recreated fresh before every run.
86
+ # Resources
87
+ agents mcp list # Show MCP servers
88
+ agents commands list # Show slash commands
89
+ agents skills list # Show skills
307
90
 
91
+ # Automation
92
+ agents exec claude "prompt" # Run agent
93
+ agents cron add job.yaml # Schedule job
94
+ agents daemon start # Start scheduler
308
95
  ```
309
- ~/.agents/jobs/daily-pr-digest/home/ <-- agent sees this as $HOME
310
- .claude/
311
- settings.json <-- generated from allow.tools
312
- src/ -> ~/src <-- symlink from allow.dirs
313
- ```
314
-
315
- Three layers of enforcement, none relying on prompt injection:
316
96
 
317
- | Layer | What it does | How |
318
- |-------|-------------|-----|
319
- | **Tool allowlist** | Restricts available tools | Agent CLI reads generated config; disallowed tools are blocked |
320
- | **HOME overlay** | Filesystem isolation | Only `allow.dirs` entries are symlinked in; everything else is invisible |
321
- | **Env sanitization** | Prevents credential leakage | Only safe env vars (`PATH`, `SHELL`, `LANG`, etc.) pass through |
97
+ Also available as `ag` - all commands work with `ag pull`, `ag list`, etc.
322
98
 
323
- The agent cannot access `~/.ssh`, `~/.aws`, `~/.gitconfig`, API keys in env vars, or anything else not explicitly allowed.
99
+ ---
324
100
 
325
101
  ## Compatibility
326
102
 
327
- | Agent | Commands | MCP | Hooks | Skills | Memory | Permissions | Jobs |
328
- |-------|----------|-----|-------|--------|--------|-------------|------|
329
- | Claude | yes | yes | yes | yes | yes | yes | yes |
330
- | Codex | yes | yes | -- | yes | yes | yes | yes |
331
- | Gemini CLI | yes | yes | yes | yes | yes | -- | yes |
332
- | Cursor | yes | yes | -- | yes | yes | -- | -- |
333
- | OpenCode | yes | yes | -- | yes | yes | yes | -- |
334
-
335
- ## All Commands
336
-
337
- ```
338
- Env
339
- status [agent] Show installed agents and sync status
340
- pull [source] [agent] Sync from .agents repo
341
- push Push config to your .agents repo
342
-
343
- Agents
344
- add <agent>[@version] Install agent CLI version
345
- remove <agent>[@version] Remove agent CLI version
346
- use <agent>@<version> Set default version (-p for project)
347
- list [agent] List installed versions
348
-
349
- Packages
350
- search <query> Search MCP and skill registries
351
- install <identifier> Install mcp:<name>, skill:<name>, or gh:<user/repo>
352
-
353
- Resources
354
- memory list|view|remove
355
- commands list|add|remove|view
356
- mcp list|add|remove|register|view
357
- skills list|add|view|remove
358
- hooks list|add|remove|view
359
- permissions list|add|remove|view
360
-
361
- Automation
362
- exec <agent> <prompt> Run agent with unified interface
363
- cron list|add|view|edit|remove|run|runs|logs|report|pause|resume
364
- daemon start|stop|status|logs
365
-
366
- Sources
367
- repo list|add|remove
368
- registry list|add|remove|enable|disable|config
369
- ```
103
+ | Agent | MCP | Commands | Skills | Memory | Permissions | Jobs |
104
+ |-------|-----|----------|--------|--------|-------------|------|
105
+ | Claude | yes | yes | yes | yes | yes | yes |
106
+ | Codex | yes | yes | yes | yes | yes | yes |
107
+ | Gemini | yes | yes | yes | yes | -- | yes |
108
+ | Cursor | yes | yes | yes | yes | -- | -- |
109
+ | OpenCode | yes | yes | yes | yes | yes | -- |
370
110
 
371
111
  ## License
372
112
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@swarmify/agents-cli",
3
- "version": "1.6.0",
3
+ "version": "1.6.1",
4
4
  "description": "Your multi-Agent manager - Agent CLIs, Agent Skills, MCP Servers, Hooks and settings",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",