bgs-modding-superpowers — Claude Code plugin: what it does
bgs-modding-superpowers — a plugin for Bethesda modpack curation: two MCP servers, an xEdit conflict audit, and agent control over your MO2 install.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install bgs-modding-superpowers@awesome-codex-pluginsWhat bgs-modding-superpowers does
Two MCP servers come with the plugin. xedit exposes nine intent tools such as xedit_session, xedit_read_record and xedit_inspect_conflicts_deep, plus xedit_call for raw daemon commands. Every call runs through a seven-stage pipeline that finishes with an audit step. bgs_kb is a local SQLite + FTS5 lookup over a bundled modding knowledge base and answers with MO2 and xEdit closed.
MO2 is driven through a broker that pairs a Python loader with a C++ plugin DLL. The agent can read profile state, fire launchers and capture child PIDs. scripts/install-mo2-control-plane.ps1 deploys that into your own install. Skills carry the rest of the workflows: setting-up-bgs-modding-environment runs first-time setup, xedit-conflict-audit walks the conflict review, writing-modpack-devlog and writing-modpack-changelog keep project docs current.
Windows and Node 22+ are required. Target games are Skyrim SE/AE, Fallout 4, Fallout 76 and Starfield; Skyrim LE and Oblivion are untested. Until BGS_MO2_ROOT points at the folder holding ModOrganizer.exe, the xedit server has no install to work against.
What it helps with
- Audit plugin conflicts in xEdit without clicking through records
- Drive an MO2 profile from the agent session
- Look up a record by pattern and read it back
- Bootstrap a modpack dev-log and release changelog
- Query the bundled modding knowledge base with MO2 closed
Example prompts for the agent
- Set up the BGS modding environment for this project folder.
- Run a conflict audit against my MO2 profile and list the records that clash.
- Add an entry to the modpack dev-log about the load order change.
How to install bgs-modding-superpowers
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install bgs-modding-superpowers@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about bgs-modding-superpowers
How to install bgs-modding-superpowers in Claude Code?
Through the marketplace, both commands in order: /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install bgs-modding-superpowers@awesome-codex-plugins.
What does bgs-modding-superpowers do?
It registers the xedit and bgs_kb MCP servers, installs an MO2 control plane, and adds skills for first-run setup, conflict audit and modpack documentation.
What do I need to run it?
Windows, Node 22+, and one target game: Skyrim SE/AE, Fallout 4, Fallout 76 or Starfield. Set BGS_MO2_ROOT to the directory containing ModOrganizer.exe, or the xedit server will not find your MO2.
Source text
bgs-modding-superpowers · MIT
# bgs-modding-superpowers
An agent plugin for Bethesda Game Studio modpack curation. Installs on OpenCode, Claude Code, and Codex. Ships xEdit and knowledge-base MCP servers, an MO2 control-plane installer, and skills that walk the agent through first-run setup, conflict audit, and project documentation.
## What's in v0.2
- **`xedit` MCP server** — nine intent tools (`xedit_session`, `xedit_list_capabilities`, `xedit_find_record`, `xedit_read_record`, `xedit_inspect_conflicts`, `xedit_inspect_conflicts_deep`, `xedit_find_records_by_pattern`, `xedit_create_child_record`, `xedit_navigate_ancestry`) plus the atomic `xedit_call` passthrough for the native xEdit daemon command set discovered at runtime via `system.capabilities`. Goes through a 7-stage harness pipeline (validate → state-check → rules → forward → envelope → audit).
- **`bgs_kb` MCP server** — local SQLite + FTS5 knowledge-base lookup (`bgs_kb_status`, `bgs_kb_query`, `bgs_kb_get`) over the bundled core BGS modding KB. Works without MO2 or xEdit running.
- **MO2 control plane** — C++ MO2 plugin DLL + Python loader + broker that lets the agent drive your MO2 instance (read profile state, run launchers, capture child PIDs). Deployed by `scripts/install-mo2-control-plane.ps1` into your own MO2.
- **xEdit hook bridge (retired)** — historical Delphi DLL retained at `tools/xedit-hook-bridge/dist/`; native `xEdit.exe -automation-serve` now handles unattended launches.
- **Skills**:
- `using-bgs-modding-superpowers` — per-session bootstrap.
- `setting-up-bgs-modding-environment` — first-run install orchestrator (MO2 detect → control plane → optional xEdit download → dev-log / changelog init → semantic smoke test).
- `xedit-automation` + `xedit-conflict-audit` — the hub skill and the W2 conflict-audit workflow.
- `writing-modpack-devlog`, `writing-modpack-changelog` — create and maintain your modpack project's documentation at runtime.
## Install
### OpenCode
Add to the `plugin` array of your `opencode.json`:
```json
{
"plugin": ["bgs-modding-superpowers@git+https://github.com/BB-84C/bgs-modding-superpowers.git"]
}
```
Full instructions: [`.opencode/INSTALL.md`](.opencode/INSTALL.md).
For a project-local vendor install, use `npm install --prefix .opencode/vendor ...` and configure the plugin as `./.opencode/vendor/node_modules/bgs-modding-superpowers`. This path is resolved from the project configuration, so a shared OpenCode server does not depend on its own working directory.
### Claude Code
```text
/plugin marketplace add BB-84C/bgs-modding-superpowers
/plugin install bgs-modding-superpowers@bgs-modding-superpowers
```
The bundled `xedit` and `bgs_kb` MCP servers are declared in [`.mcp.json`](./.mcp.json) and resolve via `${CLAUDE_PLUGIN_ROOT}`.
### Codex
Start a Codex session and paste this prompt. Your Codex agent does the install for you:
> Install the bgs-modding-superpowers plugin from `https://github.com/BB-84C/bgs-modding-superpowers`. Run these two commands and report back what `codex mcp list` shows afterwards:
>
> ```
> codex plugin marketplace add BB-84C/bgs-modding-superpowers
> codex plugin add bgs-modding-superpowers@bgs-modding-superpowers
> ```
>
> Both `xedit` and `bgs_kb` MCP servers should appear in `codex mcp list` after install — Codex auto-imports them from the plugin's `.mcp.json`. If either is missing or any step fails, surface the exact error rather than working around it.
That's it. After install, restart any open Codex session so the new skills and MCP servers load.
**Manual install** (same two commands, run yourself):
```text
codex plugin marketplace add BB-84C/bgs-modding-superpowers
codex plugin add bgs-modding-superpowers@bgs-modding-superpowers
```
**Update later** with:
```text
codex plugin marketplace upgrade bgs-modding-superpowers
```
The repo carries the materialized plugin tree at `plugins/bgs-modding-superpowers/` (Codex's marketplace schema requires the subdirectory layout). Source-of-truth files at the repo root are mirrored there by `scripts/build-portable-plugin.ps1` on every release.
## First run
Start any session in your modpack project directory and ask:
> Set up the BGS modding environment.
The `setting-up-bgs-modding-environment` skill will detect MO2, install the control plane, optionally fetch xEdit from [BB-84C/TES5Edit](https://github.com/BB-84C/TES5Edit), and initialize your dev-log + release-changelog.
You can install MO2 yourself, ask the agent to install it (explicit consent), or run in "no MO2" mode for documentation-only work.
## Requirements
- Windows. The MO2 control plane and xEdit hook bridge are Windows-only by design (modpack work is Windows-anchored).
- A target game: Skyrim SE/AE, Fallout 4, Fallout 76, or Starfield. Skyrim LE and Oblivion can work but are untested.
- Node 22+ (the bundled MCP servers run on Node).
## Pointing the xEdit MCP at your own MO2 install
Out of the box the `xedit` MCP server has no idea where your MO2 install lives. Tell it via the `BGS_MO2_ROOT` env var on the MCP server entry in your harness config; the value is the absolute path to the directory containing `ModOrganizer.exe`.
Examples:
- OpenCode (`~/.config/opencode/opencode.json`, harness MCP block — set the env on the `xedit` server entry):
```json
{
"mcp": {
"xedit": { "env": { "BGS_MO2_ROOT": "D:\\Starfield MO2" } }
}
}
```
- Codex (`~/.codex/config.toml`, after `codex plugin add`):
```toml
[mcp_servers.xedit.env]
BGS_MO2_ROOT = "D:\\Starfield MO2"
```
- Claude Code: edit the materialized plugin's `.mcp.json` env block, or set the env var in the shell that launches Claude Code.
Once set, the launcher defaults to `<BGS_MO2_ROOT>/tools/xEdit/xEdit.exe` and resolves `plugins.txt` from `<BGS_MO2_ROOT>/profiles/<profile>/`. Per-call overrides (`xedit_start({ moRoot, launcherPath, ... })`) win over the env var. The `setting-up-bgs-modding-environment` skill detects your MO2 install during first-run and walks you through wiring the env var.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Internal design docs and plans live under [`docs/internal/`](docs/internal/).
## License
MIT. See [LICENSE](LICENSE).
© awesome-bgs-mod-master contributors · MIT · hashgraph-online/awesome-codex-plugins