@maplestoryworlds/ai-cli

Configure AI coding agents — Claude Code, Cursor, Codex, and GitHub Copilot — from a single AGENTS.md. Runs on Windows, macOS, and Linux via Node.js 18+.

Install

npm install -g @maplestoryworlds/ai-cli
mswai --version    # 0.8.5 or newer

Quickstart

cd your-msw-workspace
mswai init        # scaffold AGENTS.md + hooks + skills
mswai status      # quick "is each agent installed?" digest

Precondition — commands run only inside a MapleStory Worlds local workspace folder (a directory containing Environment/config with a "CoreVersion" field).

Project flow

• Project flow map — end-to-end HTML overview of official pack sync, templates, generated agent outputs, CLI commands, and workspace files.
• Testing and feature coverage checklist — current automated test scope, feature coverage status, and required doc updates when tests or features change.

Supported agents

| Agent | Instruction file | MCP config | Skills dir | Hooks | | --- | --- | --- | --- | :---: | | Claude Code | CLAUDE.md | .mcp.json | .claude/skills/ | ✓ | | Cursor | .cursorrules | .cursor/mcp.json | .agents/skills/ (shared) | ✓ | | GitHub Copilot | .github/copilot-instructions.md | .vscode/mcp.json | .agents/skills/ (shared) | ✓ | | Codex | reads AGENTS.md natively | .codex/config.toml | .agents/skills/ (shared) | ✓ |

Hooks fire at six lifecycle events — PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop, SessionEnd (Codex skips SessionEnd) — from a shared script tree. Each agent's native config is generated from one source-of-truth EVENT_TOPICS registry, so the four agents stay in sync automatically.

Skills are delegated to skills.sh:

• Installer — every mswai init / mswai skill invocation first shells out to npx -y skills add <source> --skill <name> -a <agent-id>. If the default official source fails and --skills-global is not set, mswai falls back to the bundled copy in templates/skill/skills/.
• Catalog — the curated MSW skill list ships in templates/skill/skills.yaml, and the matching skill content ships in templates/skill/skills/. The source points at the upstream content repo MSW-Git/msw-ai-coding-plugins-official. Override the source per run with mswai init --skills <owner/repo|url|path>.

mlua-lsp ships as a pinned vendored runtime inside @maplestoryworlds/ai-cli (@maplestoryworlds/[email protected]). mswai init/update materializes it into .mswai/runtime/mlua-lsp/<version>, and MLua hook scripts prefer that workspace-local runtime before falling back to the vendored package, PATH, and npx resolution.

Commands

| Command | What it does | | --- | --- | | mswai init | Full setup. Runs instruction / hook / skill installers and materializes the vendored mlua-lsp runtime. | | mswai status | Per-agent install digest (read-only). Output: {agents:{<id>:{plugin,mcp}}}. | | mswai inspect | Detailed audit — drift breakdown for instruction / hook / skill / mcp. | | mswai update | Sync to the latest package templates. Force-recreates drifted files. | | mswai instruction | Per-feature: AGENTS.md + per-agent instruction files only. | | mswai hook | Per-feature: hook scripts + agent hook configs only. | | mswai skill | Per-feature: skills install only (delegates to npx skills add). | | mswai mcp | Per-feature: MCP server config files only. | | mswai reset | Kill stuck mlua-lsp / msw-mcp node processes. Use when npm i -g @maplestoryworlds/ai-cli fails with EBUSY on Windows. Runs from anywhere (no workspace required). |

All commands accept -h/--help and --workspace <path>. Most accept --json, -a/--agent, and -n/--dry-run. See mswai <command> --help for full flags.

mswai init flags

| Flag | Description | | --- | --- | | -a, --agent <id[,id...]> | Only set up selected agents (claude-code, cursor, codex, copilot). Repeatable. Default: all. | | -f, --force | Overwrite drifted files. | | --copy | Write a literal copy of AGENTS.md instead of the default @AGENTS.md include. | | -n, --dry-run | Show planned actions without writing. | | --json | Emit a single JSON envelope on stdout (machine-readable). Implies --silent. | | --workspace <path> | MSW workspace root. Default: current shell cwd. | | --silent | Skip interactive prompts; use flags + defaults as-is. Auto-on for --json and non-TTY stdin. | | --no-instruction / --no-hooks / --no-mcp / --no-skills / --no-mlua-lsp | Skip individual setup steps. --no-mlua-lsp skips vendored mlua-lsp runtime setup. (--no-git is accepted as a silent no-op for back-compat.) | | --mcp-var KEY=VALUE | Substitute {KEY} placeholders in mcp.yaml. Repeatable. | | --skills <source> | Override skills source (GitHub owner/repo, URL, or local path). | | --skills-global | Install skills to the user home instead of the project. | | --platform <p> | Override platform detection (windows/macos/linux). |

MCP setup

mswai mcp (and mswai init when MCP isn't disabled) writes a per-agent config file from mcp.yaml. The bundled MSW servers ship with sensible defaults for Windows and macOS — typical users do not need to pass --mcp-var:

mswai mcp                                                  # uses platform defaults
mswai mcp --mcp-var MSW_MAKER_MCP_PATH="D:\custom\path.bat"  # override default

| Variable | Used by | Default | What | | --- | --- | --- | --- | | MSW_MAKER_MCP_PATH | msw-maker-mcp (stdio) | Win: %LOCALAPPDATA%\Nexon\MapleStory Worlds\MakerMCP\msw-maker-mcp.bat · macOS: /Library/Application Support/Nexon/MapleStory Worlds/MapleStory Worlds.app/Contents/MacOS/MakerMCP | Path to the MakerMCP launcher. On Windows, %VAR% references in defaults are expanded against process.env at init time — the generated mcp file contains an absolute path like C:\Users\<you>\AppData\Local\Nexon\..., since MCP clients quote args before spawning and cmd.exe never sees the unquoted form it would expand. On macOS, the generated command launches through /bin/sh -c 'exec "$1"' so the app bundle path with spaces stays one argument for Cursor and other MCP clients. |

--mcp-var KEY=VALUE always wins over the platform default, so power users with a non-standard install can override.

API key for msw-mcp

The hosted msw-mcp server needs a Bearer token. mswai does not prompt for it — if you don't pass --mcp-var MSW_MCP_TOKEN=<key>, the issuance URL https://maplestoryworlds-insight.nexon.com/credentials/api-keys is written into the Authorization: Bearer … header as a clickable hint. Open .mcp.json (or .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml), click the URL to issue an API key, and replace it with the issued key.

mswai status — Unity Maker AI Assistant digest

A read-only command that returns a minimal per-agent install summary. Two booleans per agent:

{
  "agents": {
    "claude-code": { "plugin": true,  "mcp": true  },
    "cursor":      { "plugin": false, "mcp": false },
    "codex":       { "plugin": true,  "mcp": false },
    "copilot":     { "plugin": true,  "mcp": true  }
  }
}

• plugin — instruction file + hook files + skills dir all present and matching templates.
• mcp — MCP config file exists with the expected server entries (drift counts as true — the entries are physically there).

mswai status --workspace <ws> --json           # all 4 agents
mswai status --workspace <ws> -a copilot --json   # filter to one agent

For drift breakdowns, use mswai inspect --json instead — same envelope as init/update, with per-feature ok + message + extras.

mswai inspect — detailed audit

mswai inspect --workspace <ws> --json

Returns the full envelope used by init/update:

{
  "ok": false,
  "cwd": "...",
  "dryRun": false,
  "instruction": { "ok": true,  "message": "...", "agents": { "<id>": {...} } },
  "hook":        { "ok": true,  "message": "...", "files":  { "<path>": {...} } },
  "skill":       { "ok": false, "message": "1 agent(s) missing skills", "agents": {...} },
  "mcp":         { "ok": false, "message": "...", "targets": {...}, "servers": [...] }
}

Per-feature commands

Useful when you want to install or refresh exactly one feature:

mswai instruction --agent cursor --workspace <ws>
mswai hook        --agent cursor --workspace <ws>
mswai skill       --agent cursor --workspace <ws>
mswai mcp         --agent cursor --workspace <ws> \
                  --mcp-var MSW_MAKER_MCP_PATH=...

Each emits the same envelope shape as init, populating only its own feature key.

Programmatic usage (Unity / scripts)

mswai status --json is the canonical "is mswai installed and configured?" probe. The output is intentionally minimal so client code never has to track per-agent file paths.

mswai --version                                            # quick install probe (~50ms post-warmup)
mswai status --workspace "$WS" --json                      # per-agent digest
mswai inspect --workspace "$WS" --json                     # detailed drift report
mswai init --no-mcp --no-mlua-lsp --agent copilot --workspace "$WS" --json
mswai mcp  --agent copilot --workspace "$WS" \
           --mcp-var MSW_MAKER_MCP_PATH=... --json

Exit codes (all commands):

• 0 — success
• 1 — operation failed (drift detected, file write skipped, workspace marker missing)
• 2 — argument error

Syncing the official pack

For maintainers, sync:official-pack pulls the latest source templates from https://github.com/MSW-Git/msw-ai-coding-plugins-official, updates templates/skill/skills.yaml, templates/instruction/AGENTS.md, and templates/hook/**, then regenerates templates/generated/**.

npm run sync:official-pack -- --dry-run
npm run sync:official-pack
npm run sync:official-pack -- --ref main

Use --dry-run before applying changes. Use --repo-dir <path> only when testing against a local checkout instead of GitHub. When committing a sync, include the upstream tag in the commit title. If the upstream repo has no tag, use its latest release commit title instead, for example chore: sync official pack release v0.2.4. Do not add installed metadata files just to record the source revision.

Keeping up to date

npm install -g @maplestoryworlds/ai-cli@latest
mswai update

update syncs hook scripts, .claude/settings.json, MCP config, and skills to the package's latest templates. AGENTS.md is preserved if you've customized it — pass --force to overwrite.

Recovering from a broken setup

| Symptom | Fix | | --- | --- | | mswai status shows plugin:false after install | Check mswai inspect --json to find which sub-feature drifted | | Hook scripts, settings.json, or MCP config tampered/deleted | mswai update | | CLAUDE.md / .cursorrules / .github/copilot-instructions.md broken | mswai init --force | | Skills directory empty | Re-run mswai skill (or mswai init); default official skills fall back to the bundled copy if npx skills add fails | | MLua diagnostics start slowly or fail to find the package | Reinstall or update @maplestoryworlds/ai-cli, then run mswai update to refresh hook scripts | | npm i -g @maplestoryworlds/ai-cli fails with EBUSY (Windows) | A live mlua language server is holding the install dir. Run mswai reset to SIGKILL stuck mlua-lsp processes, then retry npm i | | Start over | Delete generated files → mswai init |

Windows notes

No symlinks or elevated permissions required. Each per-agent instruction file is a plain text file containing @AGENTS.md, resolved by the agent at load time. Pass --copy to write a standalone copy instead.