# Plugdev

> Use when the user says "use PlugDev", or when testing, booting, hot-reloading, or joining a local Minecraft Paper, Spigot, Folia, or Purpur plugin project — PlugDev CLI setup, plug run, plug doctor, multi-module pick, deps, headless server commands, Folia restart, listing screenshots/GIFs (Windows capture scenarios), agent wiring (Cursor/Claude/Codex), and optional MCP tools for structured control.

- Skill: `mattbaconz/plugdev` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add mattbaconz/plugdev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mattbaconz/plugdev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: mattbaconz (https://skillmd.com/u/mattbaconz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mattbaconz/plugdev

---


# PlugDev test loop

PlugDev is the local **test environment** for Minecraft plugins. Prefer it over manually starting Paper and copying JARs.

For agent work, use structured MCP tools when available or CLI `--json` from the plugin project directory. Check `plug -V` first: background capture and native player controls require CLI 1.4.0+ (MCP 0.5.0+). Read [capture.md](references/capture.md) for screenshots, GIFs, animated cursors, GUI clicks, movement and test players. Reuse the user's configured client; do not replace their Prism instance or move desktop focus. If the installed skill contains references/local-preferences.md, read it for preferences specific to that machine.

## First moves (agent: set up the best env)

Inspect the project instructions, configuration, selected module and running server first. Reuse the installed CLI and working environment. For setup requested by the user:

1. **Install CLI** if `plugdev` / `plug` is missing from PATH:
   ```powershell
   npm install -g @plugdev/cli
   ```
   Or one-shot: `npx @plugdev/cli@latest <command>`.

2. **Initialize the project** if there is no `plugdev.yml`:
   ```powershell
   plugdev init --setup
   ```
   This writes project config and prefetches the selected runtime into `~/.plugdev/`. Agent rules and MCP are optional separate setup; do not overwrite working project instructions. `agent install --mcp` merges `.cursor/mcp.json` and `.mcp.json`. After the first MCP write, the editor needs to reload MCP.

3. If Codex project wiring is requested:
   ```powershell
   plugdev agent install --codex
   ```

4. **Boot the loop:**
   ```powershell
   plug run
   ```

5. If boot or detection fails, run `plug doctor` and fix what it reports (Java 21+, Node 22+, Gradle/Maven). Paper/Folia 26.x needs Java 25+.

6. Multi-module reactors: `plugdev module list` then `plugdev module use <name>` (or TUI Module).

7. **Background screenshots/GIFs (Windows):** read [capture.md](references/capture.md). Start the local server, then use `capture shot|gif|run`. Select an existing Fabric 26.1.2 Prism instance with `client start --instance "FO 26.1.2"` for native screenshots, animated cursors, GUI clicks and player control. Otherwise automatic launch uses an isolated Minecraft 1.21.4 profile with capped rendering and idle shutdown; existing clients can be bound explicitly. Capture never activates a window or injects desktop input. Requires FFmpeg `gfxcapture` and FFprobe. Bots cannot render screenshots.

## Day loop

| Goal | Command |
|------|--------|
| Interactive TUI | `plugdev` / `plug` |
| One-shot test loop | `plug run` |
| Wipe worlds | `plug clean` |
| Cold run folder | `plug clean --all` |
| Multi-module pick | `plugdev module list|use` |
| Test deps | `plugdev deps add|remove|list` |
| Headless (agents) | `plugdev server start|stop|status|command|logs` |
| Listing shots/GIFs (Windows) | `plugdev capture run` / `shot` / `gif` |
| Scripting | add `--json` |

After the server is ready, joining players are **auto-OP** when `dev.op` is true (default). Type console commands in the **same terminal** (RCON), e.g. `list`, `gamemode creative @a`.

## MCP (optional structured tools)

When `.cursor/mcp.json` or `.mcp.json` includes PlugDev (via `init --mcp` / `agent install --mcp`), prefer MCP tools for headless control:

- `plugdev_doctor`, `plugdev_setup`, `plugdev_init`
- `plugdev_build_plugin`, `plugdev_sync_plugin`
- `plugdev_start_server`, `plugdev_stop_server`, `plugdev_get_server_status`
- `plugdev_tail_logs`, `plugdev_run_server_command`, `plugdev_op_player`
- `plugdev_list_modules`, `plugdev_use_module`
- `plugdev_list_deps`, `plugdev_add_dep`, `plugdev_remove_dep`
- `plugdev_agent_install`, `plugdev_cache_prefetch`, `plugdev_cache_status`, `plugdev_clean`
- `plugdev_list_configs`, `plugdev_get_config`, `plugdev_set_config`
- `plugdev_open_client` — embedded client join
- `plugdev_capture_doctor`, `plugdev_capture_shot`, `plugdev_capture_gif`, `plugdev_capture_run`
- `plugdev_run_test_loop` — build → sync → start → OP

CLI remains primary for interactive `plug run` (server + watch + client join). MCP is the same loop without a TTY.

Install MCP alone: `npx -y @plugdev/mcp` (stdio).

## Hard rules

- Prefer `plug run` over manually starting Paper.
- Do **not** use Bukkit `/reload` — PlugDev uses safe JAR reload via bootstrap.
- On **Folia**, prefer full restart over safe reload.
- Optional `--hotswap` / `watch.reload.java: hotswap` is method-body JDWP redefine only; structural changes fall back to safe reload.
- Do not delete `~/.plugdev` unless the user asks (`plugdev cache clear`).
- Background capture needs a non-minimized rendered Windows client and unlocked desktop. Never refocus Minecraft or substitute desktop capture. Use `capture client` for background startup; `open --client` is the interactive launcher. Do not claim headless or untested platform support.

## Facts

| Item | Value |
|------|--------|
| Bins | `plug` and `plugdev` (same CLI) |
| Config | `plugdev.yml` |
| Run dir | `.plugdev/run/` |
| Cache | `~/.plugdev/` |
| Modules | `plugdev module list|use` (multi-module Maven/Gradle) |
| Deps | `plugdev deps add|remove|list` (+ TUI Dependencies) |
| Reload | Safe JAR reload (not `/reload`); optional `--hotswap` for method bodies |
| Folia | Prefer full restart over safe reload |
| Headless | `plugdev server start|stop|status|command|logs` + `--json` |
| MCP | `npx @plugdev/mcp` — structured tools for the same loop |
| Skill install | `npx skills add mattbaconz/plugdev --skill plugdev` |
| Docs | https://pluglabs.app/plugdev |