allagents 1.6.0 → 1.7.0

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 (3) hide show
  1. package/README.md +77 -401
  2. package/dist/index.js +436 -213
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,280 +1,83 @@
1
1
  # AllAgents
2
2
 
3
- CLI tool for managing multi-repo AI agent workspaces with plugin synchronization across multiple AI clients.
3
+ [![npm](https://img.shields.io/npm/v/allagents)](https://www.npmjs.com/package/allagents)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![Docs](https://img.shields.io/badge/docs-allagents.dev-blue)](https://allagents.dev)
4
6
 
5
- ## Why AllAgents?
7
+ Write AI agent skills once. Sync to 23 clients. Manage across multiple repos.
6
8
 
7
- **The Problem:** AI coding assistants (Claude, Copilot, Cursor, Codex, etc.) each have their own configuration formats and directory structures. If you want to share skills across multiple projects or use multiple AI clients, you need to manually copy and transform files.
9
+ AllAgents keeps your AI tooling (skills, agents, hooks, MCP servers) in one workspace and syncs it to every client your team uses — Claude, Copilot, Cursor, Codex, Gemini, and 18 more.
8
10
 
9
- **AllAgents solves this by:**
11
+ ## Quick Start
10
12
 
11
- | Feature | Claude Code Plugins | AllAgents |
12
- |---------|--------------------|-----------|
13
- | Scope | Single project | Multi-repo workspace |
14
- | Client support | Claude only | 23 AI clients |
15
- | File location | Runtime lookup from cache | Copied to workspace (git-versioned) |
16
- | Project structure | AI config mixed with code | Separate workspace repo |
13
+ ```bash
14
+ # Create a workspace from a shared template
15
+ npx allagents workspace init my-workspace --from myorg/templates/nodejs
16
+ cd my-workspace
17
17
 
18
- ### Key Differentiators
18
+ # Install plugins
19
+ npx allagents plugin install code-review@claude-plugins-official
19
20
 
20
- 1. **Multi-repo workspaces** - One workspace references multiple project repositories. Your AI tooling lives separately from your application code.
21
+ # Sync to all configured clients
22
+ npx allagents update
23
+ ```
21
24
 
22
- 2. **Multi-client distribution** - Write plugins once, sync to all clients. AllAgents transforms and copies files to each client's expected paths.
25
+ No cloning required — AllAgents fetches the `workspace.yaml` directly from GitHub and sets up everything.
23
26
 
24
- 3. **Workspace is a git repo** - Unlike Claude's runtime plugin system, AllAgents copies files into your workspace. Team members get the same AI tooling via git.
27
+ ## How It Works
25
28
 
26
- 4. **Clean separation** - Project repos stay clean. AI configuration lives in the workspace.
29
+ 1. **Configure** your workspace with repos, plugins, and target clients in `workspace.yaml`
30
+ 2. **Sync** — AllAgents copies skills, agents, hooks, and MCP servers to each client's expected paths
31
+ 3. **Work** — every team member gets identical AI tooling via git, across any client they choose
27
32
 
28
33
  ```
29
34
  ┌─────────────────┐
30
- │ Marketplace │ (plugin source - GitHub repos)
35
+ │ Marketplace │ GitHub repos containing plugins
31
36
  └────────┬────────┘
32
37
  │
33
38
  ▼
34
39
  ┌─────────────────┐
35
- │ AllAgents │ (sync & transform)
40
+ │ AllAgents │ sync & transform
36
41
  │ sync │
37
42
  └────────┬────────┘
38
43
  │
39
44
  ┌────┴────┬────────┬─────────┐
40
45
  ▼ ▼ ▼ ▼
41
- .claude/ .agents/ .cursor/ .factory/ (client paths)
42
- ```
43
-
44
- ## Installation
45
-
46
- ```bash
47
- # Using npm
48
- npm install -g allagents
49
-
50
- # Or run directly without installing
51
- npx allagents
52
- ```
53
-
54
- ## Quick Start
55
-
56
- ```bash
57
- # Create a new workspace
58
- allagents workspace init my-workspace
59
- cd my-workspace
60
-
61
- # Or initialize from a remote GitHub template
62
- allagents workspace init my-workspace --from owner/repo/path/to/template
63
-
64
- # Add a marketplace (or let auto-registration handle it)
65
- allagents plugin marketplace add anthropics/claude-plugins-official
66
-
67
- # Install plugins to workspace
68
- allagents plugin install code-review@claude-plugins-official
69
- allagents plugin install my-plugin@someuser/their-repo
70
-
71
- # Sync plugins to workspace
72
- allagents update
73
- ```
74
-
75
- ### Initialize from Remote Template
76
-
77
- Start a new workspace instantly from any GitHub repository containing a `workspace.yaml`:
78
-
79
- ```bash
80
- # From GitHub URL
81
- allagents workspace init ~/my-project --from https://github.com/myorg/templates/tree/main/nodejs
82
-
83
- # From shorthand
84
- allagents workspace init ~/my-project --from myorg/templates/nodejs
85
-
86
- # From repo root (looks for .allagents/workspace.yaml or workspace.yaml)
87
- allagents workspace init ~/my-project --from myorg/templates
88
- ```
89
-
90
- This fetches the workspace configuration directly from GitHub - no cloning required.
91
-
92
- ## Commands
93
-
94
- ### Workspace Commands
95
-
96
- ```bash
97
- # Initialize a new workspace from template
98
- allagents workspace init <path>
99
- allagents workspace init <path> --from <source> # From local path or GitHub URL
100
-
101
- # Sync all plugins to workspace (non-destructive)
102
- allagents update [options]
103
- --force Force re-fetch of remote plugins even if cached
104
- --dry-run Preview changes without applying
105
-
106
- # Non-destructive sync: your files are safe
107
- # - First sync overlays without deleting existing files
108
- # - Subsequent syncs only remove files AllAgents previously synced
109
- # - Tracked in .allagents/sync-state.json
110
-
111
- # Show status of workspace and plugins
112
- allagents workspace status
113
-
114
- # Add a repository to the workspace (auto-detects git remote source)
115
- allagents workspace repo add <path>
116
- allagents workspace repo add <path> --description "My project"
117
-
118
- # Remove a repository from the workspace
119
- allagents workspace repo remove <path>
120
-
121
- # List all repositories in the workspace
122
- allagents workspace repo list
123
- ```
124
-
125
- ### VSCode Workspace Generation
126
-
127
- When `vscode` is included in the `clients` list, `allagents update` automatically generates a `.code-workspace` file. Repository paths are resolved to absolute paths. Plugin folders are included with prompt/instruction file location settings for Copilot.
128
-
129
- ```yaml
130
- # workspace.yaml
131
- clients:
132
- - vscode
133
- - claude
134
- ```
135
-
136
- #### Output filename
137
-
138
- The output filename defaults to `<dirname>.code-workspace`. Override with `vscode.output`:
139
-
140
- ```yaml
141
- # workspace.yaml
142
- vscode:
143
- output: my-project
144
- ```
145
-
146
- #### Template file
147
-
148
- Create `.allagents/template.code-workspace` for VSCode-specific settings, launch configurations, extensions, and extra folders. The template supports `{path:../...}` placeholders that resolve to absolute paths using repository paths from workspace.yaml.
149
-
150
- ```json
151
- {
152
- "folders": [
153
- { "path": "{path:../Shared}", "name": "SharedLib" }
154
- ],
155
- "settings": {
156
- "cSpell.words": ["myterm"],
157
- "chat.agent.maxRequests": 999,
158
- "chat.useAgentSkills": true
159
- },
160
- "launch": {
161
- "configurations": [
162
- {
163
- "type": "node",
164
- "name": "dev",
165
- "cwd": "{path:../myapp}/src",
166
- "runtimeExecutable": "npm",
167
- "runtimeArgs": ["run", "dev"]
168
- }
169
- ]
170
- },
171
- "extensions": {
172
- "recommendations": ["dbaeumer.vscode-eslint"]
173
- }
174
- }
175
- ```
176
-
177
- The generated workspace includes:
178
- - Repository folders from workspace.yaml (resolved to absolute paths, listed first)
179
- - Template folders (deduplicated against repository folders)
180
- - All other template content (settings, launch, extensions) with `{repo:..}` placeholders resolved
181
-
182
- ### Plugin Marketplace Commands
183
-
184
- ```bash
185
- # List registered marketplaces
186
- allagents plugin marketplace list
187
-
188
- # Add a marketplace from GitHub or local path
189
- allagents plugin marketplace add <source>
190
- # Examples:
191
- # allagents plugin marketplace add anthropics/claude-plugins-official
192
- # allagents plugin marketplace add /path/to/local/marketplace
193
-
194
- # Remove a marketplace
195
- allagents plugin marketplace remove <name>
196
-
197
- # Update marketplace(s) from remote
198
- allagents plugin marketplace update [name]
46
+ .claude/ .github/ .cursor/ .agents/ client paths
199
47
  ```
200
48
 
201
- ### Plugin Commands
202
-
203
- ```bash
204
- # Install a plugin to .allagents/workspace.yaml (auto-registers marketplace if needed)
205
- allagents plugin install <plugin@marketplace>
206
-
207
- # Remove a plugin from .allagents/workspace.yaml
208
- allagents plugin uninstall <plugin>
209
-
210
- # List available plugins from marketplaces
211
- allagents plugin list [marketplace]
212
-
213
- # Validate a plugin or marketplace structure
214
- allagents plugin validate <path>
215
- ```
216
-
217
- ### Skills Commands
218
-
219
- ```bash
220
- # Add a specific skill from a GitHub repo
221
- allagents skills add reddit --from ReScienceLab/opc-skills
222
-
223
- # Add a skill via GitHub URL (skill name extracted from path)
224
- allagents skills add https://github.com/owner/repo/tree/main/skills/my-skill
225
-
226
- # List all skills and their enabled/disabled status
227
- allagents skills list
228
-
229
- # Disable a skill without uninstalling its plugin
230
- allagents skills remove brainstorming
231
-
232
- # Re-enable a previously disabled skill
233
- allagents skills add brainstorming
234
- ```
235
-
236
- ### GitHub Overrides
237
-
238
- For **Copilot** and **VSCode**, AllAgents copies GitHub-specific files from a plugin's `.github/` folder into the workspace's `.github/` directory:
239
-
240
- - `.github/prompts/` — prompt files
241
- - `.github/agents/` — agent overrides
242
- - `.github/hooks/` — hook overrides
243
- - `copilot-instructions.md` — root Copilot instructions
49
+ ## Why AllAgents?
244
50
 
245
- Root `agents/` and `hooks/` directories in a plugin also map to `.github/agents/` and `.github/hooks/` for Copilot/VSCode.
51
+ Tools like `npx skills` and `npx plugins` install skills to one project for one or two clients. AllAgents manages your entire AI tooling stack — skills, agents, hooks, commands, and MCP servers — across multiple repos and all your clients, from a single declarative config.
246
52
 
247
- ## .allagents/workspace.yaml
53
+ | | `npx skills` | `npx plugins` | `npx allagents` |
54
+ |---|---|---|---|
55
+ | **Config** | Imperative | Imperative | Declarative (`workspace.yaml`) |
56
+ | **Scope** | Single project | Single project | Multi-repo workspace |
57
+ | **Artifacts** | Skills | Skills, agents, hooks, commands, MCP | Skills, agents, hooks, commands, MCP |
58
+ | **Clients** | 43 agents | 2 (Claude, Cursor) | 23 clients simultaneously |
59
+ | **Team sharing** | Each dev runs install | Each dev runs install | Git-versioned — clone and go |
60
+ | **Ongoing sync** | One-shot install | One-shot install | `allagents update` keeps everything current |
61
+ | **Workspace awareness** | None | None | WORKSPACE-RULES injected so AI knows all repos and skills |
62
+ | **Provider resilience** | Per-client | Per-client | Switch clients instantly — same tooling everywhere |
248
63
 
249
- The workspace configuration file lives in `.allagents/workspace.yaml` and defines repositories, plugins, workspace files, and target clients:
64
+ ## workspace.yaml
250
65
 
251
66
  ```yaml
252
- # Workspace file sync (optional) - copy files from a shared source
253
67
  workspace:
254
- source: ../shared-config # Default base for relative paths
68
+ source: ../shared-config
255
69
  files:
256
- - AGENTS.md # String shorthand: same source and dest
257
- - source: docs/guide.md # Object form: explicit source
258
- dest: GUIDE.md # Optional dest (defaults to basename)
259
- - dest: CUSTOM.md # File-level source override
260
- source: ../other-config/CUSTOM.md
261
- - dest: AGENTS.md # GitHub source
262
- source: owner/repo/path/AGENTS.md
70
+ - AGENTS.md
263
71
 
264
72
  repositories:
265
73
  - path: ../my-project
266
- source: github
267
- repo: myorg/my-project
268
- description: Main project repository
74
+ description: Main project
269
75
  - path: ../my-api
270
- source: github
271
- repo: myorg/my-api
272
76
  description: API service
273
77
 
274
78
  plugins:
275
- - code-review@claude-plugins-official # plugin@marketplace format
276
- - context7@claude-plugins-official
277
- - my-plugin@someuser/their-repo # fully qualified for custom marketplaces
79
+ - code-review@claude-plugins-official
80
+ - my-plugin@someuser/their-repo
278
81
 
279
82
  clients:
280
83
  - claude
@@ -282,190 +85,63 @@ clients:
282
85
  - cursor
283
86
  ```
284
87
 
285
- ### Workspace File Sync
286
-
287
- The `workspace:` section enables syncing files from external sources to your workspace root. This is useful for sharing agent configurations (AGENTS.md, CLAUDE.md) across multiple projects.
288
-
289
- **Key behaviors:**
290
- - **Source of truth is remote** - Local copies are overwritten on every sync
291
- - **Deleted files are restored** - If you delete AGENTS.md locally, sync restores it
292
- - **WORKSPACE-RULES injection** - AGENTS.md and CLAUDE.md automatically get workspace discovery rules injected
293
-
294
- **Source resolution:**
295
- | Format | Example | Resolves to |
296
- |--------|---------|-------------|
297
- | String shorthand | `AGENTS.md` | `{workspace.source}/AGENTS.md` |
298
- | Relative source | `source: docs/guide.md` | `{workspace.source}/docs/guide.md` |
299
- | File-level override | `source: ../other/file.md` | `../other/file.md` (relative to workspace) |
300
- | GitHub source | `source: owner/repo/path/file.md` | Fetched from GitHub cache |
301
-
302
- **GitHub sources** are fetched fresh on every sync (always pulls latest).
303
-
304
- ### Plugin Spec Format
305
-
306
- Plugins use the `plugin@marketplace` format:
307
-
308
- | Format | Example | Description |
309
- |--------|---------|-------------|
310
- | Well-known | `code-review@claude-plugins-official` | Uses known marketplace mapping |
311
- | owner/repo | `my-plugin@owner/repo` | Auto-registers GitHub repo, looks in `plugins/` |
312
- | owner/repo/subpath | `my-plugin@owner/repo/extensions` | Looks in custom subdirectory |
313
-
314
- The subpath format is useful when plugins aren't in the standard `plugins/` directory:
315
-
316
- ```yaml
317
- plugins:
318
- - feature-dev@anthropics/claude-plugins-official/plugins # explicit plugins/ dir
319
- - my-addon@someuser/repo/addons # custom addons/ dir
320
- - tool@org/monorepo/packages/tools # nested path
321
- ```
322
-
323
- ### Well-Known Marketplaces
324
-
325
- These marketplace names auto-resolve to their GitHub repos:
326
-
327
- - `claude-plugins-official` → `anthropics/claude-plugins-official`
328
-
329
- ### Supported Clients
330
-
331
- AllAgents supports 23 AI coding assistants:
88
+ ## Commands
332
89
 
333
- #### Universal Clients (share `.agents/skills/`)
90
+ | Command | Description |
91
+ |---|---|
92
+ | `allagents workspace init <path>` | Create a workspace (optionally `--from owner/repo`) |
93
+ | `allagents update` | Sync all plugins to workspace |
94
+ | `allagents plugin install <spec>` | Install a plugin |
95
+ | `allagents plugin uninstall <spec>` | Remove a plugin |
96
+ | `allagents plugin list` | List available plugins |
97
+ | `allagents skills add <name>` | Add a skill from a repo |
98
+ | `allagents skills list` | List skills and status |
99
+ | `allagents workspace status` | Show workspace state |
100
+ | `allagents self update` | Update AllAgents CLI |
334
101
 
335
- | Client | Skills | Agent File | Hooks | Commands | MCP |
336
- |--------|--------|------------|-------|----------|-----|
337
- | copilot | `.github/skills/` | `AGENTS.md` | `.github/hooks/` | No | `.vscode/mcp.json` · `~/.config/Code/User/mcp.json` |
338
- | codex | `.agents/skills/` | `AGENTS.md` | No | No | `.codex/config.toml` · `codex mcp` CLI |
339
- | opencode | `.agents/skills/` | `AGENTS.md` | No | `.opencode/commands/` | No |
340
- | gemini | `.agents/skills/` | `GEMINI.md` | No | No | No |
341
- | ampcode | `.agents/skills/` | `AGENTS.md` | No | No | No |
342
- | vscode | `.agents/skills/` | `AGENTS.md` | No | No | `.vscode/mcp.json` · `~/.config/Code/User/mcp.json` |
343
- | replit | `.agents/skills/` | `AGENTS.md` | No | No | No |
344
- | kimi | `.agents/skills/` | `AGENTS.md` | No | No | No |
102
+ See the [full CLI reference](https://allagents.dev/reference/cli/) for all options.
345
103
 
346
- #### Provider-Specific Clients
104
+ ## Supported Clients
347
105
 
348
- | Client | Skills | Agent File | Hooks | Commands | MCP |
349
- |--------|--------|------------|-------|----------|-----|
350
- | claude | `.claude/skills/` | `CLAUDE.md` | `.claude/hooks/` | `.claude/commands/` | `.mcp.json` · `claude mcp` CLI |
351
- | cursor | `.cursor/skills/` | `AGENTS.md` | No | No | No |
352
- | factory | `.factory/skills/` | `AGENTS.md` | `.factory/hooks/` | No | No |
353
- | openclaw | `skills/` | `AGENTS.md` | No | No | No |
354
- | windsurf | `.windsurf/skills/` | `AGENTS.md` | No | No | No |
355
- | cline | `.cline/skills/` | `AGENTS.md` | No | No | No |
356
- | continue | `.continue/skills/` | `AGENTS.md` | No | No | No |
357
- | roo | `.roo/skills/` | `AGENTS.md` | No | No | No |
358
- | kilo | `.kilocode/skills/` | `AGENTS.md` | No | No | No |
359
- | trae | `.trae/skills/` | `AGENTS.md` | No | No | No |
360
- | augment | `.augment/skills/` | `AGENTS.md` | No | No | No |
361
- | zencoder | `.zencoder/skills/` | `AGENTS.md` | No | No | No |
362
- | junie | `.junie/skills/` | `AGENTS.md` | No | No | No |
363
- | openhands | `.openhands/skills/` | `AGENTS.md` | No | No | No |
364
- | kiro | `.kiro/skills/` | `AGENTS.md` | No | No | No |
106
+ **23 AI coding assistants** across two tiers:
365
107
 
366
- > **Note:** Universal clients share the same `.agents/skills/` directory. See [GitHub Overrides](#github-overrides) for how Copilot and VSCode handle `.github/` content. MCP servers from plugins are synced to each client's native config format — unsupported clients show a warning during sync.
108
+ **Universal** (share `.agents/skills/`): Copilot, Codex, OpenCode, Gemini, Amp Code, VSCode, Replit, Kimi
367
109
 
368
- ## Marketplace Structure
110
+ **Provider-specific**: Claude, Cursor, Factory, OpenClaw, Windsurf, Cline, Continue, Roo, Kilo, Trae, Augment, Zencoder, Junie, OpenHands, Kiro
369
111
 
370
- Marketplaces contain multiple plugins:
371
-
372
- ```
373
- my-marketplace/
374
- ├── plugins/
375
- │ ├── code-review/
376
- │ │ └── skills/
377
- │ └── debugging/
378
- │ └── skills/
379
- └── README.md
380
- ```
112
+ See the [client support matrix](https://allagents.dev/reference/clients/) for paths, hooks, commands, and MCP support per client.
381
113
 
382
114
  ## Plugin Structure
383
115
 
384
- Each plugin follows this structure:
385
-
386
116
  ```
387
117
  my-plugin/
388
- ├── skills/ # Skill directories with SKILL.md (all clients)
118
+ ├── skills/ # Reusable prompts (all clients)
389
119
  │ └── debugging/
390
120
  │ └── SKILL.md
391
- ├── commands/ # Command files (.md) - Claude, OpenCode
392
- │ ├── build.md
393
- │ └── deploy.md
394
- ├── .github/ # GitHub overrides (Copilot, VSCode)
395
- │ └── prompts/
396
- │ └── review.md
397
- ├── hooks/ # Hook files (Claude/Factory only)
398
- │ └── pre-commit.md
399
- ├── .mcp.json # MCP server configs (Claude, Codex, VSCode)
400
- └── AGENTS.md # Agent configuration (optional)
401
- ```
402
-
403
- ### Skill Validation
404
-
405
- Skills must have a valid `SKILL.md` file with YAML frontmatter:
406
-
407
- ```yaml
408
- ---
409
- name: my-skill # Required: lowercase, alphanumeric + hyphens, max 64 chars
410
- description: Description of the skill # Required
411
- allowed-tools: # Optional
412
- - Read
413
- - Write
414
- model: claude-3-opus # Optional
415
- ---
416
-
417
- # Skill Content
418
-
419
- Skill instructions go here...
121
+ ├── agents/ # Agent definitions
122
+ ├── commands/ # Slash commands (Claude, OpenCode)
123
+ ├── hooks/ # Lifecycle hooks (Claude, Factory, Copilot)
124
+ ├── .github/ # Copilot/VSCode overrides
125
+ └── .mcp.json # MCP server configs
420
126
  ```
421
127
 
422
- ### Self Commands
128
+ ## Documentation
423
129
 
424
- ```bash
425
- # Update to latest version (auto-detects package manager)
426
- allagents self update
427
-
428
- # Force a specific package manager
429
- allagents self update --npm
430
- allagents self update --bun
431
- ```
432
-
433
- When using the interactive TUI, AllAgents automatically checks for newer versions in the background and shows a notice on startup when an update is available.
434
-
435
- ## Storage Locations
436
-
437
- ```
438
- ~/.allagents/
439
- ├── marketplaces.json # Registry of marketplaces
440
- ├── version-check.json # Cached update check (auto-managed)
441
- └── marketplaces/ # Cloned marketplace repos
442
- ├── claude-plugins-official/
443
- └── someuser-their-repo/
444
- ```
130
+ Full documentation at [allagents.dev](https://allagents.dev):
445
131
 
446
- ## Development
447
-
448
- ```bash
449
- # Install dependencies
450
- bun install
451
-
452
- # Run in development
453
- bun run dev workspace init test-ws
454
-
455
- # Run tests
456
- bun run test
457
-
458
- # Type check
459
- bun run typecheck
460
-
461
- # Build
462
- bun run build
463
- ```
132
+ - [Getting Started](https://allagents.dev/getting-started/introduction/)
133
+ - [Workspaces Guide](https://allagents.dev/guides/workspaces/)
134
+ - [Plugins Guide](https://allagents.dev/guides/plugins/)
135
+ - [Agent Portability](https://allagents.dev/guides/agent-portability/)
136
+ - [Client Support Matrix](https://allagents.dev/reference/clients/)
137
+ - [Configuration Reference](https://allagents.dev/reference/configuration/)
464
138
 
465
139
  ## Related Projects
466
140
 
467
- - [dotagents](https://github.com/iannuttall/dotagents) - Unified AI agent configuration management
468
- - [vercel-labs/skills](https://github.com/vercel-labs/skills) - Universal skills for AI coding assistants
141
+ - [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) — Universal skills for AI coding assistants
142
+ - [skillpm](https://github.com/sbroenne/skillpm) — npm-native package manager for Agent Skills
143
+ - [skills-npm](https://github.com/antfu/skills-npm) — Discover agent skills shipped in npm packages
144
+ - [dotagents](https://github.com/iannuttall/dotagents) — Unified AI agent configuration management
469
145
 
470
146
  ## License
471
147