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 · 한국어

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

$ 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:

/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

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 <id> | 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 <file> | 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 <file> --target <id> | Apply manifest MCPs to Cursor, Codex, etc. | | apply -f <file> --dry-run --json | Preview apply as JSON | | apply -f <file> --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 <id> | Show one domain's loadout items | | domains --json | Domains as JSON | | show <id> | Show one catalog entry (config, install, homepage) | | show <id> --json | Entry as JSON | | search <query> | Search catalog by id, name, description, signals, domains | | search <query> --type mcp\|skill\|hook | Limit search to one item type | | search <query> --limit N | Cap results (default 20) | | search <query> --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:

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.

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.

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 (token saver). Shown only when you ask, labeled ⚠ unverified, and never auto-applied.

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 | React, Vue, Svelte, Next — anything in a browser | | Backend / API | Servers, APIs, databases | | Data / ML / Notebooks | Python data work, training, analysis | | Research / Academic | Literature review, notebooks, papers, experiments | | DevOps / Infra | CI/CD, Docker, Terraform, Kubernetes | | Mobile | iOS, Android, React Native, Flutter | | Game Development | Godot, Unity, Unreal | | Security-sensitive | Auth, payments, PII | | Docs / Writing / Office | Docs and real Word/Excel/PDF/PPT deliverables | | General / Any project | The always-useful baseline |

Full browsable index: docs/domains/.

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:

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

See 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.