@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

Quickstart

cd your-msw-workspace
mswai init        # scaffold AGENTS.md, hooks, MCP config, and install skills
mswai status      # verify everything is set up correctly

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

Supported agents

| Agent | Instruction file | Skills | MCP | Hooks | | --- | --- | :---: | :---: | :---: | | Claude Code | CLAUDE.md | ✓ | ✓ .mcp.json | ✓ | | Cursor | .cursorrules | ✓ | ✓ .cursor/mcp.json | ✓ | | GitHub Copilot | .github/copilot-instructions.md | ✓ | ✓ .vscode/mcp.json | ✓ | | Codex | reads AGENTS.md natively | ✓ | — | ✓ |

Hooks fire at 4 lifecycle events — PreToolUse, PostToolUse, SessionStart, UserPromptSubmit — across all agents from shared scripts.

Commands

| Command | Description | | ------- | ----------- | | mswai init | Create AGENTS.md, per-agent links, hooks, MCP config, and install skills. Idempotent. | | mswai status | Check that all agent files and skills are correctly set up. | | mswai update | Sync to the latest package templates (AGENTS.md, hooks, MCP config, skills). |

mswai init options

| Flag | Description | | ---- | ----------- | | -a, --agent <id[,id...]> | Only set up selected agents (claude-code, cursor, codex, copilot). Repeatable. | | -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 anything. | | --json | Emit a single JSON result object. | | --workspace <path> | Run as if from <path> (default: current directory). | | --no-skills | Skip skill installation. | | --skills <source> | Override the skills source (GitHub owner/repo, URL, or local path). | | --skills-global | Install skills to the user home instead of the project. | | --no-agents-md | Skip AGENTS.md and per-agent link creation. | | --no-hooks | Skip hook scripts and hook config files. | | --no-git | Skip git init and the initial commit. | | --no-mcp | Skip MCP config generation. | | --mcp-var KEY=VALUE | Substitute {KEY} placeholders in mcp.yaml (repeatable). | | -h, --help | Show help. |

MCP setup

MCP config requires the MapleStory Worlds client path:

mswai init --mcp-var MSW_CLIENT_PATH="C:\MSW\Client"

Windows

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

Keeping up to date

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

update syncs hook scripts, settings, MCP config, and skills to the latest templates. AGENTS.md is left untouched if you've customized it — pass --force to overwrite.

Recovering from broken setup

| Situation | Fix | |---|---| | Hook scripts, settings.json, or MCP config tampered/deleted | mswai update | | CLAUDE.md / .cursorrules / .github/copilot-instructions.md broken | mswai init --force | | Start over | Delete generated files → mswai init |