# Loadout

> 🎯 Loadout — profile your project and gear up Claude Code with the right skills, MCP servers & hooks, in one command. A recommender + installer, not a list you read.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sukoji-loadout`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sukoji](https://agentstack.voostack.com/s/sukoji)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sukoji](https://github.com/sukoji)
- **Source:** https://github.com/sukoji/loadout
- **Website:** https://www.npmjs.com/package/claude-loadout

## Install

```sh
agentstack add mcp-sukoji-loadout
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

### Loadout looks at your project and sets up Claude Code for it.

It works out which MCP servers, hooks, and skills fit your stack, shows you a short ranked list with a
reason for each, and installs the ones you pick, writing the config for you. So you don't have to read a
500-item "awesome" list and copy-paste install commands by hand.

It also works with other agents: full setup for Claude Code, plus MCP servers for Codex, Cursor, opencode,
Gemini CLI and OpenClaw.

[English](README.md) · [한국어](README.ko.md)

---

> **TL;DR:** point it at a repo, it recommends the Claude Code extensions that fit that repo, and applies the ones you pick.

## The problem

The Claude Code ecosystem has thousands of skills, MCP servers, hooks, and plugins, spread across dozens of
"awesome" lists. Those lists are good for discovery, but that's all they are: you read hundreds of entries,
guess which ones apply to you, and copy-paste install commands one by one.

Loadout does the other half. Point it at a project and it tells you what to install for *that* project, then
sets it up for you.

## What it does

```text
$ npx claude-loadout

🎯 Loadout  — gearing up Claude Code for this project

Detected: package.json, next, react, tailwind, prettier, playwright
Best-fit domains: Frontend / Web UI, General / Any project

Recommended loadout:

 1  Playwright (browser automation)  [MCP server]
     Drive a real browser — navigate, click, assert, screenshot — via accessibility snapshots.
     why: matches react, next, playwright

 2  Auto-format JS/TS on edit (Prettier)  [Hook/setting]
     After Claude edits a file, run Prettier on it so the diff is always clean.
     why: matches package.json, prettier, react

 3  Context7 (up-to-date docs)  [MCP server]
     Pulls version-accurate docs for thousands of libraries into context — kills hallucinated APIs.
     ...

Install which? numbers e.g. 1,3,4  ·  'a' = all  ·  Enter = skip: 1,2,3

✅ Applied:
  .mcp.json          + playwright, context7
  .claude/settings.json + format-js-on-edit
```

It scans your project (languages, frameworks, CI, existing config), matches it to one or more domains, and
ranks a short loadout with a one-line reason for each item. You pick what you want and it writes the config,
merging into `.mcp.json` and `.claude/settings.json`, never overwriting what's already there, and flagging any
tokens you still need to fill in.

## Two ways to use it

### 1. Inside Claude Code (recommended)

Add the marketplace once, then the recommender is a slash command:

```text
/plugin marketplace add sukoji/loadout
/plugin install loadout@loadout

/loadout:recommend     # profile this repo, recommend a loadout, and apply what you pick
/loadout:browse        # just browse the catalog by domain, no changes
```

`/loadout:recommend` reads your repo the way a human would, then uses `AskUserQuestion` to let you check the
items you want — and applies them in place.

### 2. As a standalone CLI

```bash
cd your-project
npx claude-loadout            # interactive
npx claude-loadout --dry-run  # just show the recommendation
npx claude-loadout --all      # apply the whole recommended loadout
npx claude-loadout doctor     # audit tokens, hook deps, security gaps
npx claude-loadout doctor --fix  # apply auto-writable suggestions (MCP + hooks)
npx claude-loadout export     # team loadout → .loadout.json
npx claude-loadout apply -f .loadout.json   # apply shared manifest
npx claude-loadout --help     # full flag list
```

Zero dependencies, ~1s for scan/recommend, nothing to install globally.

### CLI flags

| Flag | What it does |
| :-- | :-- |
| *(none)* | Interactive — pick items by number |
| `--dry-run` / `-d` | Show recommendations only; write nothing |
| `--json` | Print recommendations as JSON (no write; good for CI) |
| `--all` / `-a` / `-y` | Apply the top recommendations without prompting |
| `--all --json` | Apply top recommendations; print receipts as JSON only |
| `--discover` | Also surface **unverified** community skills |
| `--target ` | Write MCP config for `cursor`, `codex`, `gemini`, `opencode`, `openclaw`, or `all` |
| `--list-targets` | List agents and config file paths |
| `export` | Write team loadout manifest → `.loadout.json` (includes `installed` ids) |
| `export --json` | Print manifest JSON to stdout |
| `apply -f ` | Apply a shared team loadout |
| `apply --ids id1,id2` | Apply specific catalog ids (e.g. from `doctor --json` suggestions) |
| `apply --suggestions` | Apply top recommendations for this repo (no manifest file) |
| `apply --suggestions --mcp-only` | Suggestions: MCP servers only (skip skills/hooks) |
| `apply --suggestions --limit N` | Cap how many suggestions to apply (default 5) |
| `apply -f  --target ` | Apply manifest MCPs to Cursor, Codex, etc. |
| `apply -f  --dry-run --json` | Preview apply as JSON |
| `apply -f  --json` | Apply and print receipts as JSON |
| `doctor` | Audit: tokens, hook deps, cross-agent dupes, gaps |
| `doctor --fix` | Apply auto-writable suggestions (MCP + hooks) and print skill install steps |
| `doctor --fix --mcp-only` | Fix MCP servers only |
| `doctor --fix --hooks-only` | Fix hooks/settings only |
| `apply --suggestions --hooks-only` | Apply hook/setting suggestions only |
| `doctor --fix --dry-run` | Preview what `--fix` would apply |
| `doctor --json` | Audit JSON with `domains`, `signals`, `suggestions`, `fixCommand*`, `applyCommand*`, and `summary` (`healthy` / `optionalOnly`; exit 1 when fixes needed) |
| `doctor --quiet` | Warnings and fixes only (skip OK lines) |
| `doctor --require-healthy` | Exit 1 unless `summary.healthy` (optional plugins still count as healthy) |
| `domains` | List catalog domains, signal hints, and loadout sizes |
| `domains ` | Show one domain's loadout items |
| `domains --json` | Domains as JSON |
| `show ` | Show one catalog entry (config, install, homepage) |
| `show  --json` | Entry as JSON |
| `search ` | Search catalog by id, name, description, signals, domains |
| `search  --type mcp\|skill\|hook` | Limit search to one item type |
| `search  --limit N` | Cap results (default 20) |
| `search  --json` | Search results as JSON |
| `stats` | Catalog counts (domains, tiers, types) |
| `stats --json` | Stats as JSON |
| `signals` | Print detected project signals and matched domains |
| `signals --json` | Signals + domains as JSON (`version`, `root`, `signals`, `domains`, `count`) |

**Team loadouts:** run `export` in a reference repo, commit `.loadout.json`, then teammates run
`apply -f .loadout.json` (add `--target cursor` for non-Claude agents).

**CI automation:** profile a repo and apply gaps without prompts:

```bash
npx claude-loadout doctor --json > profile.json
# profile.json includes applyCommand / applyCommandMcpOnly / applyCommandIds
npx claude-loadout apply --suggestions --mcp-only --json
```

Copy-paste GitHub Actions job: [examples/ci-doctor.yml](examples/ci-doctor.yml).

**Non-interactive shells** (CI, pipes): use `--dry-run`, `--json`, `--all`, or `--all --json` — otherwise Loadout prints recommendations and exits without hanging on input.

### What auto-applies vs what you do

| Kind | Loadout writes it? | You still need to… |
| :-- | :-- | :-- |
| MCP servers | ✅ merges into `.mcp.json` (or agent MCP file) | Fill API keys; OAuth on first use for hosted servers |
| Hooks & settings | ✅ merges into `.claude/settings.json` | Install hook deps (`jq`, `ruff`, …); on Windows use Git Bash/WSL for shell hooks |
| Built-in skills (`/init`, `/code-review`) | ❌ already in Claude Code | Run the slash command when you want it |
| Marketplace plugins (Exa, Superpowers, …) | ❌ prints `/plugin install …` | Run those commands in Claude Code |

Run `npx claude-loadout doctor` anytime to see unfilled placeholders and missing PATH tools.

## Works with your agent — not just Claude Code

MCP servers are portable across today's agents; only the config file and format differ. Loadout writes
the right one for each. Skills and hooks are Claude Code-native, so for other agents Loadout applies the
MCP servers and tells you what's Claude-only.

```bash
npx claude-loadout --target codex        # writes ~/.codex-style .codex/config.toml
npx claude-loadout --target cursor        # writes .cursor/mcp.json
npx claude-loadout --target claude,cursor # apply to several at once
npx claude-loadout --target all           # every supported agent
npx claude-loadout --list-targets         # see them all
```

| Target (`--target`) | Agent | Config file | MCP format |
| :-- | :-- | :-- | :-- |
| `claude` *(default)* | Claude Code | `.mcp.json` + `.claude/settings.json` | `mcpServers` + skills/hooks |
| `cursor` | Cursor | `.cursor/mcp.json` | `mcpServers` |
| `gemini` | Gemini CLI | `.gemini/settings.json` | `mcpServers` |
| `opencode` | opencode | `opencode.json` | `mcp` (`type: local`) |
| `codex` | Codex CLI | `.codex/config.toml` | `[mcp_servers.*]` (TOML) |
| `openclaw` | OpenClaw | `~/.openclaw/openclaw.json` | `mcp.servers` |

If you don't pass `--target`, Loadout targets Claude Code and points out any other agents it detects in the project.

## Why this is different

| Everyone else | Loadout |
| :-- | :-- |
| A flat list you read and filter yourself | Profiles *your* repo and recommends for it |
| "Here are 500 things" | "Here are the 6 things *you* need, and why" |
| Copy-paste install commands by hand | Writes `.mcp.json` / `settings.json` for you |
| Discovery only | Discovery **+ apply**, in one step |

It's also a **plugin marketplace** and a **browsable catalog** — so discovery, recommendation, and install all
live in one place.

## Coverage — three tiers (not just a fixed list)

Loadout pulls from three tiers, so it reaches the whole ecosystem without ever blindly applying something unvetted:

- **Curated (38)** — hand-verified MCP servers, hooks & skills. Safe to auto-apply; every npx package is checked to resolve on npm (`npm run verify:mcp`) and smoke-started in release checks (`npm run test:mcps`).
- **Official marketplace (~240)** — Anthropic's official plugin directory, ingested automatically. Surfaced when they match your stack, installed via `/plugin`.
- **Community (`--discover`)** — well-known community skills like [caveman](https://github.com/JuliusBrussee/caveman) (token saver). Shown only when you ask, labeled **⚠ unverified**, and **never auto-applied**.

```bash
npx claude-loadout            # curated + matching official plugins
npx claude-loadout --discover # also surface community skills (review before installing)
```

## Domains

Loadout organizes its curated catalog by the kind of project you're working on:

| Domain | For |
| :-- | :-- |
| [Frontend / Web UI](docs/domains/frontend.md) | React, Vue, Svelte, Next — anything in a browser |
| [Backend / API](docs/domains/backend-api.md) | Servers, APIs, databases |
| [Data / ML / Notebooks](docs/domains/data-ml.md) | Python data work, training, analysis |
| [Research / Academic](docs/domains/research.md) | Literature review, notebooks, papers, experiments |
| [DevOps / Infra](docs/domains/devops.md) | CI/CD, Docker, Terraform, Kubernetes |
| [Mobile](docs/domains/mobile.md) | iOS, Android, React Native, Flutter |
| [Game Development](docs/domains/game-dev.md) | Godot, Unity, Unreal |
| [Security-sensitive](docs/domains/security.md) | Auth, payments, PII |
| [Docs / Writing / Office](docs/domains/docs-writing.md) | Docs and real Word/Excel/PDF/PPT deliverables |
| [General / Any project](docs/domains/general.md) | The always-useful baseline |

Full browsable index: [docs/domains/](docs/domains/README.md).

## How it works

```
your repo ──▶ scan (signals) ──▶ match domains ──▶ rank loadout ──▶ you pick ──▶ apply
             package.json,        frontend +        by signal        multi-      .mcp.json
             requirements.txt,    general           strength         select      .claude/settings.json
             Dockerfile, .env…                                                    + install commands
```

- **Catalog** (`plugins/loadout/catalog/*.json`) is the single source of truth — MCP servers, skills, and
  hooks, each tagged with the domains and signals it fits. Both the skill and the CLI read the same data.
- **Recommender** scores every domain by how many of its signals appear in your project, unions the top
  domains' loadouts, drops anything you already have, and ranks the rest.
- **Apply** deep-merges into your config. Hooks append to the right event arrays; MCP servers land under
  `mcpServers`; skills print the exact `/plugin` or built-in commands to run.

## Contributing a catalog entry

The catalog is meant to grow with the community. Add an entry to the relevant file in
`plugins/loadout/catalog/`, tag it with `domains` and `signals`, run the checks, and open a PR:

```bash
npm run validate     # catalog integrity: unique ids, required fields, domain references
npm run build:docs   # regenerate docs/domains/ from the catalog
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the entry schema.

## Roadmap

**Done (0.3.x)**
- [x] Publish `claude-loadout` to npm for `npx`
- [x] `loadout doctor` / `doctor --fix` — audit and auto-apply MCP + hooks
- [x] Team loadouts — `export` / `apply -f .loadout.json`, `--ids`, `--suggestions`
- [x] Cross-agent targets — Cursor, Codex, Gemini, opencode, OpenClaw
- [x] Catalog browse — `domains`, `show`, `search`, `stats`
- [x] Research + game-dev domains; signal-gated recommendations

**Next**
- [ ] Runtime-verified curated catalog growth (research MCPs only after `npm run test:mcps`)
- [ ] Optional CI publish via repo `NPM_TOKEN` secret (workflow already ships)

**Later**
- [ ] More domains (embedded, browser extensions, Rust systems)
- [ ] Demo GIF / directory submissions (awesome-claude-code, marketplaces)

## License

MIT © sukoji. The catalog links to third-party tools owned by their respective authors; Loadout only curates
and configures them.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sukoji](https://github.com/sukoji)
- **Source:** [sukoji/loadout](https://github.com/sukoji/loadout)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/claude-loadout

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sukoji-loadout
- Seller: https://agentstack.voostack.com/s/sukoji
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.