mxsetup

name	mxSetup
description	This skill should be used when a developer sets up mxLore on a new PC, runs a fresh Claude Code install, updates the global mx-rules block in ~/.claude/CLAUDE.md, refreshes skills/hooks from GitHub, or reinstalls the mxMCPProxy. Triggers "neuer PC", "fresh install", "onboard me", "/mxSetup", "update mx-rules", "mx-rules block veraltet", "reinstall proxy", "skills aktualisieren".
user-invocable	true
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
argument-hint	<api-key> | --update | --update-rules | --update-proxy | --with-superpowers

/mxSetup — Developer Onboarding (~30 seconds)

AI-Steno: !=forbidden →=use ⚡=critical ?=ask ⚡ !Python !jq !sed for file operations. Only Write/Read/Edit tools + Bash for claude mcp and curl. ⚡ Bash: Single-line. !Multi-line !Heredocs !Newlines in commands.

When to trigger this skill

• claude mcp list returns empty or lacks mxai-knowledge
• mxMCPProxy binary (.exe on Windows) missing or version mismatch vs server
• mx-rules marker block in ~/.claude/CLAUDE.md outdated or missing
• New PC / fresh Claude Code install
• User says "/mxSetup", "onboard me", or "neuer PC"
• Skills folder out of date (upstream updates in MicrotronX/mxLore-skills)

Prerequisites

• Required CLI tools: curl, unzip, claude (Claude Code CLI). Git-Bash on Windows includes curl+unzip.
• Node.js — Recommended. Required for 5 of 8 hooks (Orchestrate, Recall-Gate, Recall-Outcome). Without Node.js the session runs with limited functionality (no state tracking, no Recall-Gate). Installation: https://nodejs.org/

First Installation (with API key)

Phase 1: MCP Connection

1. Check claude mcp list → already has mxai-knowledge? → "Use --update"
2. ?user: "Server URL? (e.g. http://localhost:8080/mcp)"
   • URL must end with /mcp
3. Register MCP:

claude mcp add -s user --transport http mxai-knowledge "<SERVER-URL>" --header "Authorization: Bearer <API-KEY>"

4. mx_ping() → Success? Note admin_port. Error? → Abort.

Phase 2: Install Skills from GitHub (~5 seconds)

⚡ EXACT URL — DO NOT invent! Source: MicrotronX/mxLore-skills (GitHub). !mxai-org !mxai-tech !other repos.

Downloads the zip, extracts skills into ~/.claude/skills/, hooks into ~/.claude/hooks/, reference into ~/.claude/reference/, stamps the bundle's setup-version.json into ~/.claude/setup-version.json (client-side version tracking — mx_session_start reports it for the admin session view), and stages CLAUDE.md as /tmp/mxLore-skills-CLAUDE.md for Phase 5c:

bash ~/.claude/skills/mxSetup/scripts/install-skills.sh

Phase 2+3 may run in parallel (independent downloads); Phase 4+5 remain sequential.

⚡ Scope limit: install-skills.sh copies hook FILES into ~/.claude/hooks/ but does NOT modify ~/.claude/settings.json. Hook registration (PreToolUse / PostToolUse / Stop / etc. entries) happens in Phase 5b below — running install-skills.sh standalone leaves hook files on disk but inactive until settings.json is updated.

Optional: REPO_REF=v2.4.0 bash ~/.claude/skills/mxSetup/scripts/install-skills.sh pins a release tag instead of main HEAD (default remains main until mxLore-skills cuts tagged releases).

⚡ !PowerShell !Invoke-WebRequest — always use curl+unzip in Bash (works everywhere).

Phase 3: Install Proxy (cross-platform: Windows / macOS arm64 / macOS Intel)

1. Collect download URLs from the mx_ping response (the install script picks the right one by uname — you just forward all candidates):
   • proxy_download_url (+ proxy_sha256) — Windows, server-hosted Delphi proxy. Set when admin_port > 0.
   • proxy_download_url_darwin_arm64 — macOS Apple Silicon (GitHub release asset, size-checked).
   • proxy_download_url_darwin_amd64 — macOS Intel.
   • If none of these are present in mx_ping: warning, skip proxy install.
2. Run the installer once with the candidates as env vars. It detects the platform via uname, installs to ~/.claude/mxMCPProxy.exe (Windows) or ~/.claude/mxMCPProxy (macOS, executable bit set), and verifies integrity (Windows: SHA256 if available; macOS: size >100KB — release assets carry no server-side sha256):

PROXY_URL="<proxy_download_url>" \
EXPECTED_SHA256="<proxy_sha256 or omit>" \
PROXY_URL_DARWIN_ARM64="<proxy_download_url_darwin_arm64 or omit>" \
PROXY_URL_DARWIN_AMD64="<proxy_download_url_darwin_amd64 or omit>" \
bash ~/.claude/skills/mxSetup/scripts/install-proxy.sh

3. Create proxy INI (Write tool → ~/.claude/mxMCPProxy.ini):

[Server]
Url=<SERVER-URL>
ApiKey=<API-KEY>
ConnectionTimeout=10000
ReadTimeout=120000

[Agent]
Polling=1
PollInterval=15

Phase 4: Switch MCP to Proxy

The installed binary is ~/.claude/mxMCPProxy.exe (Windows) or ~/.claude/mxMCPProxy (macOS) — use the matching path:

claude mcp remove mxai-knowledge -s user
# Windows:
claude mcp add -s user mxai-knowledge -- "<HOME>/.claude/mxMCPProxy.exe"
# macOS:
claude mcp add -s user mxai-knowledge -- "$HOME/.claude/mxMCPProxy"

mx_ping() → Success? Continue. Error? Offer HTTP fallback.

Phase 5: Config

⚡ Read ~/.claude/settings.json with Read tool, then extend via Edit tool. !Delete/overwrite existing entries. Only add missing ones.

5a. Permissions — Add the following to permissions.allow (if not present):

"mcp__mxai-knowledge__*",
"Skill(mxSave)",
"Skill(mxDecision)",
"Skill(mxPlan)",
"Skill(mxSpec)",
"Skill(mxDesignChecker)",
"Skill(mxBugChecker)"

5a-Deny. Path guards — Add to permissions.deny (create the array if it does not exist yet):

"Read(**/__history/**)",
"Read(**/__recovery/**)",
"Read(**/*.~*~)"

Keeps the Delphi IDE's revision backups (Unit1.pas.~235~, __recovery\) out of context: a stale revision still compiles, so quoting it as current silently reverts already-fixed logic. Covers the Read tool plus — best-effort, per the permissions docs — Grep, Glob, @file mentions and the Bash file commands Claude Code recognises (cat, head, tail, sed); not arbitrary subprocesses. ⚡ Use the cwd-relative **/… form shown above, not a leading slash — in user settings Read(/__history/**) resolves against ~/.claude/, not against the project. Inert on non-Delphi machines (the patterns simply never match). Rationale → reference/delphi.md → "IDE artefacts are not source".

5b. Hooks — Check each hook block. If entry missing, add it. If present, do not duplicate.

⚡ Node.js check BEFORE hook installation:

node --version 2>/dev/null

If node not found: show warning:

"Node.js not found. 5 of 8 hooks (Orchestrate, Recall-Gate, Recall-Outcome) will not work without Node.js. Session runs with limited functionality (no state tracking, no Recall-Gate). Installation: https://nodejs.org/" → Only install Bash hooks, skip JS hooks (PreCompact/PostCompact prompts are DORMANT — see pointer below).

Hooks table (Event → hooks → Requires) — see references/hooks-table.md for details. ⚡ Load-bearing: without Node.js, 5 of 8 hooks degrade (see references file).

5b-StatusLine — Add statusLine block at top level of settings.json (NOT inside hooks):

"statusLine": {
  "type": "command",
  "command": "bash ~/.claude/hooks/statusline-command.sh"
}

Shows: <slug> | <model> | <context%> | <$cost> | <tasks>. Reads slug from CLAUDE.md (**Slug:** line, accepts both backticked and plain format). ⚡ Legacy path ~/.claude/statusline-command.sh (pre-2026-04): delete it and ensure command points to ~/.claude/hooks/statusline-command.sh — all hooks live under ~/.claude/hooks/ for consistency.

PreCompact / PostCompact prompts — DORMANT, do NOT install. See references/dormant-precompact.md for rationale and re-activation steps. Manual workaround: user calls /mxSave before /compact and mx_briefing after.

5c. CLAUDE.md — Use /tmp/mxLore-skills-CLAUDE.md (saved in Phase 2). Three-branch merge logic (no file / marker present / marker absent) — see references/claude-md-merge.md for details. Afterwards: rm /tmp/mxLore-skills-CLAUDE.md.

5d. Agent Inbox: mkdir -p ~/.claude/agent_inbox

Phase 6: Done

=== mxLore Setup Complete ===

| Component | Status |
|-----------|--------|
| MCP | Connected (<URL>) |
| Skills | X installed |
| Hooks | Y installed |
| Proxy | OK / MISSING |
| CLAUDE.md | OK |

Next steps:
1. Restart Claude Code
2. Switch to project directory
3. Run /mxInitProject

Optional: /mxSetup --with-superpowers installs the superpowers bridge plugin
(enhanced brainstorming / plan-execution rigour) — not required, mx*-skills run standalone.

Update Modes

--update (full refresh)

Runs Phase 2 (skills + hooks + reference from GitHub), Phase 5 (config + ~/.claude/CLAUDE.md mx-rules marker block), and proxy version-check (same flow as Phase 3, download only if version differs). Use after upstream mxLore-skills changes or when several things are out of date.

Optional: CLEAN=1 ~/.claude/skills/mxSetup/scripts/install-skills.sh removes stale mx*/ dirs before re-copy. Use only if you have NO local unsynced edits in your mx*-skills.

--update-rules (mx-rules marker only — fast path)

• --update-rules — Re-runs Phase 2 (which downloads the full skills bundle) and Phase 5c (CLAUDE.md mx-rules marker merge). Skills + hooks get refreshed as collateral; if you want only the marker block updated without skill refresh, edit ~/.claude/CLAUDE.md manually between the markers.

--update-proxy (proxy binary swap only)

Only re-runs Phase 3: mx_ping() → forward per-platform URLs → install-proxy.sh → replace ~/.claude/mxMCPProxy[.exe] (the script picks Windows/macOS by uname). INI left untouched. Use when the server build moved ahead of the local proxy.

⚡ Stop the running proxy first (taskkill /IM mxMCPProxy.exe /F on Windows) — staging+mv mitigates file lock but a clean swap is more reliable.

--with-superpowers (optional bridge plugin)

Installs the optional superpowers plugin (Claude Code official marketplace). It provides brainstorming, executing-plans, subagent-driven-development, systematic-debugging etc. The mx*-skills work fully without it; when present they use it for extra rigour.

claude plugin install superpowers@claude-plugins-official

⚡ Opt-in only — never installed by the default /mxSetup, --update, --update-rules or --update-proxy flows (no forced third-party dependency — gh#2). Marketplace claude-plugins-official is built into Claude Code; if absent, run claude plugin marketplace add first. Verify after install: claude plugin list shows superpowers.

Rules

• !mx_onboard_developer — Skills come from GitHub, not from the server
• !Python !jq — Write/Edit tools for files, Bash only for curl/claude-mcp
• API key never displayed — only last 4 characters (mxk_****15c)
• Skills always overwritten — GitHub = source of truth
• Encoding: UTF-8 without BOM
• MCP scope: ALWAYS -s user
• Interactive questions (?user) → AskUserQuestion tool (structured options) !freetext