@swarmify/agents-mcp 0.2.9 → 0.2.11
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.
- package/README.md +116 -14
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,19 +4,68 @@
|
|
|
4
4
|
[](./LICENSE)
|
|
5
5
|
[](https://nodejs.org)
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**SubAgents and Swarms for any MCP client.** Spawn parallel agents from Claude, Codex, Gemini, or any tool that speaks MCP.
|
|
8
8
|
|
|
9
9
|
Part of [Swarmify](https://github.com/muqsitnawaz/swarmify) - multi-agent coding in your IDE.
|
|
10
10
|
|
|
11
11
|
[Homepage](https://swarmify.co/#agents-mcp) | [NPM](https://www.npmjs.com/package/@swarmify/agents-mcp) | [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=swarmify.swarm-ext) | [Demo Video](https://www.youtube.com/watch?v=rbeoKhDxK8E)
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Cross-Platform Agent Orchestration
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
```
|
|
16
|
+
MCP Protocol
|
|
17
|
+
|
|
|
18
|
+
+---------------------+---------------------+
|
|
19
|
+
| | |
|
|
20
|
+
Claude Code Codex Gemini CLI
|
|
21
|
+
(MCP Client) (MCP Client) (MCP Client)
|
|
22
|
+
| | |
|
|
23
|
+
+---------------------+---------------------+
|
|
24
|
+
|
|
|
25
|
+
+-------------------+
|
|
26
|
+
| agents-mcp |
|
|
27
|
+
| (MCP Server) |
|
|
28
|
+
+-------------------+
|
|
29
|
+
|
|
|
30
|
+
+---------------------+---------------------+
|
|
31
|
+
| | |
|
|
32
|
+
claude CLI codex CLI gemini CLI
|
|
33
|
+
(SubAgent) (SubAgent) (SubAgent)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Any client can spawn any agent.** Claude can spawn Codex. Gemini can spawn Claude. Cursor can spawn all three. The MCP protocol is the universal interface that makes this interoperability possible.
|
|
37
|
+
|
|
38
|
+
## SubAgents and Swarms
|
|
39
|
+
|
|
40
|
+
This server enables two multi-agent patterns:
|
|
41
|
+
|
|
42
|
+
**SubAgents** - Hierarchical delegation where an orchestrator spawns specialized agents for specific tasks. Each agent works in isolation and reports back to the parent.
|
|
43
|
+
|
|
44
|
+
**Swarms** - Multiple agents working in parallel on different parts of a problem. The orchestrator coordinates, assigns non-overlapping files, and synthesizes results.
|
|
45
|
+
|
|
46
|
+
Both patterns use the same four tools. The orchestrator decides the pattern.
|
|
47
|
+
|
|
48
|
+
### Why Cross-Platform Matters
|
|
49
|
+
|
|
50
|
+
Without this server, each agent is siloed:
|
|
51
|
+
- Claude Code has built-in subagents, but only Claude
|
|
52
|
+
- Codex has no native subagent support
|
|
53
|
+
- Gemini CLI has no native subagent support
|
|
54
|
+
|
|
55
|
+
With this server, every MCP client gets the same capabilities. Mix models based on their strengths:
|
|
56
|
+
|
|
57
|
+
| Workflow | How It Works |
|
|
58
|
+
|----------|--------------|
|
|
59
|
+
| **Opus for planning, Codex for speed** | Use Claude Opus as orchestrator to design architecture, spawn Codex agents for fast, cheap implementation |
|
|
60
|
+
| **Claude for research, Cursor for code** | Claude explores codebase and plans approach, Cursor (Composer) writes the code |
|
|
61
|
+
| **Parallel specialists** | Claude reviews security while Codex adds validation - simultaneously |
|
|
62
|
+
| **Codex spawning Claude** | When Codex hits something needing deeper reasoning, it spawns Claude |
|
|
63
|
+
|
|
64
|
+
You control the cost tradeoffs. Expensive models for planning, fast models for execution.
|
|
16
65
|
|
|
17
66
|
**4 tools:** `Spawn`, `Status`, `Stop`, `Tasks`
|
|
18
67
|
**3 modes:** `plan` (read-only), `edit` (can write), `ralph` (autonomous)
|
|
19
|
-
**Background processes:**
|
|
68
|
+
**Background processes:** Agents run headless, survive IDE restarts
|
|
20
69
|
|
|
21
70
|
## Quick Start
|
|
22
71
|
|
|
@@ -35,21 +84,42 @@ opencode mcp add
|
|
|
35
84
|
# Name: Swarm, Command: npx -y @swarmify/agents-mcp
|
|
36
85
|
```
|
|
37
86
|
|
|
38
|
-
The server auto-discovers which agent CLIs you have installed.
|
|
87
|
+
The server auto-discovers which agent CLIs you have installed. Once connected, your agent gains the ability to spawn and coordinate other agents.
|
|
39
88
|
|
|
40
89
|
## What It Costs
|
|
41
90
|
|
|
42
91
|
This server is free and open source.
|
|
43
92
|
|
|
44
|
-
Each
|
|
93
|
+
Each agent uses your own API keys. Spawning 3 Claude agents means 3x your normal Claude API cost. No hidden fees.
|
|
45
94
|
|
|
46
|
-
##
|
|
95
|
+
## Example: Swarm in Action
|
|
47
96
|
|
|
48
|
-
After installing, try this in Claude:
|
|
97
|
+
After installing, try this in Claude Code:
|
|
49
98
|
|
|
50
99
|
> Spawn a codex agent to add input validation to src/api/users.ts, and a claude agent to review the security implications
|
|
51
100
|
|
|
52
|
-
The orchestrating agent
|
|
101
|
+
The orchestrating agent spawns both agents in parallel:
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
Claude Code (Orchestrator)
|
|
105
|
+
|
|
|
106
|
+
+-- Spawn(codex, "add input validation to src/api/users.ts")
|
|
107
|
+
| |
|
|
108
|
+
| v
|
|
109
|
+
| Codex Agent -----> modifies src/api/users.ts
|
|
110
|
+
|
|
|
111
|
+
+-- Spawn(claude, "review security implications")
|
|
112
|
+
|
|
|
113
|
+
v
|
|
114
|
+
Claude Agent -----> analyzes changes, reports findings
|
|
115
|
+
|
|
|
116
|
+
+-- Status(task_name) -----> polls for completion
|
|
117
|
+
|
|
|
118
|
+
v
|
|
119
|
+
Synthesizes results from both agents
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The orchestrator decides when to spawn, what to assign, and how to combine results. The MCP server just provides the tools.
|
|
53
123
|
|
|
54
124
|
|
|
55
125
|
|
|
@@ -160,7 +230,43 @@ The server is a tool. Your orchestrating agent (Claude, etc.) decides how to use
|
|
|
160
230
|
|
|
161
231
|
## Under the Hood
|
|
162
232
|
|
|
163
|
-
|
|
233
|
+
### How Agents Communicate
|
|
234
|
+
|
|
235
|
+
Agents communicate through the filesystem, not shared memory:
|
|
236
|
+
|
|
237
|
+
```
|
|
238
|
+
Orchestrator SubAgent
|
|
239
|
+
| |
|
|
240
|
+
+-- Spawn ------------------> |
|
|
241
|
+
| |
|
|
242
|
+
| writes to stdout
|
|
243
|
+
| |
|
|
244
|
+
| ~/.agents/agents/{id}/stdout.log
|
|
245
|
+
| |
|
|
246
|
+
+-- Status -----------------> reads log, parses events
|
|
247
|
+
| |
|
|
248
|
+
<-- files changed, messages ---+
|
|
249
|
+
| |
|
|
250
|
+
+-- (repeat until done) -------+
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Each agent writes to its own log file (`stdout.log`). The Status tool reads these logs, normalizes events across different agent formats, and returns a summary. This design means:
|
|
254
|
+
|
|
255
|
+
- **Persistence**: Agents survive IDE restarts. Reconnect via Status/Tasks.
|
|
256
|
+
- **Debugging**: Full logs available at `~/.agents/agents/{id}/`
|
|
257
|
+
- **No shared state**: Agents don't talk to each other directly. The orchestrator coordinates.
|
|
258
|
+
|
|
259
|
+
### Storage
|
|
260
|
+
|
|
261
|
+
Data lives at `~/.agents/`:
|
|
262
|
+
```
|
|
263
|
+
~/.agents/
|
|
264
|
+
config.json # Agent configuration
|
|
265
|
+
agents/
|
|
266
|
+
{agent-id}/
|
|
267
|
+
metadata.json # task, type, mode, status
|
|
268
|
+
stdout.log # Raw agent output
|
|
269
|
+
```
|
|
164
270
|
|
|
165
271
|
**Plan mode** is read-only:
|
|
166
272
|
- Claude: `--permission-mode plan`
|
|
@@ -189,10 +295,6 @@ Config lives at `~/.agents/config.json`. See [AGENTS.md](./AGENTS.md) for full c
|
|
|
189
295
|
|
|
190
296
|
This MCP server works standalone with any MCP client. For the best experience - full-screen agent terminals, session persistence, fast navigation - install the [Agents extension](https://marketplace.visualstudio.com/items?itemName=swarmify.swarm-ext) for VS Code/Cursor.
|
|
191
297
|
|
|
192
|
-
## Storage
|
|
193
|
-
|
|
194
|
-
Data at `~/.agents/`. Requires Node.js >= 18.17.
|
|
195
|
-
|
|
196
298
|
## License
|
|
197
299
|
|
|
198
300
|
MIT
|
package/package.json
CHANGED