Skip to content

agent-install.md

Latest commit

 

History

History
100 lines (74 loc) · 4.76 KB

agent-install.md

File metadata and controls

100 lines (74 loc) · 4.76 KB
Raw

Install RPGDev — instructions for an AI coding agent

You are an AI coding agent (Claude Code, Codex, …) and your user said something like "read https://github.com/kitepon-rgb/rpgdev and install RPGDev for me." Follow this file.

Principle (how to decide what to do)

Default to letting the scripts do the work. Each step below is a script that does its part automatically and self-reports the outcome. Your only judgment is per step: run the script, read its report, and do a manual step only when a script tells you it couldn't (it always says why and what to do instead). In practice the only inherently-manual point is the Windows admin firewall step when you are on WSL2 — everything else the scripts handle.

RPGDev is distributed on npm; the user runs the published package. To update later: npm install -g rpgdev@latest.

Step 0 — read the environment

  • Which agent are you wiring up: Claude Code, Codex, or both? (Default: the one you are.)
  • Scope: this project (default) or the whole machine (--user, home-level config)?
  • Platform: macOS / Windows / WSL2 / bare Linux.

Step 1 — install the package

npm install -g rpgdev

Step 2 — hooks (let the script write them)

Run --apply for the chosen provider/scope. It writes the hook config into the correct settings file safely: it backs up the original, writes atomically, only touches .hooks, keeps the user's own hooks, and is idempotent (re-running refreshes paths instead of duplicating).

rpgdev setup --apply --claude          # Claude Code, this project
rpgdev setup --apply --codex           # Codex, this project
rpgdev setup --apply --all             # both
rpgdev setup --apply --claude --user   # Claude Code, home-level (~/.claude/settings.json)
  • Lines starting with ✓ mean it wrote them — you're done with this step.
  • Lines starting with ! (and a non-zero exit) mean it refused to write automatically because it couldn't do so safely (e.g. the existing settings file is invalid JSON, or has an unexpected shape). Then, and only then, fall back to doing it yourself: run rpgdev setup --<provider> (no --apply) to get the exact config + target path, and merge it by hand following the safety rules in install-hooks.md (touch only .hooks, keep existing hooks, back up first).

Step 3 — firewall (Windows / WSL2 only)

The single hub runs on the Windows host; the host firewall must allow WSL2/Windows traffic to it.

rpgdev setup-firewall
  • On the Windows host it applies a reboot-stable allow rule at both firewall layers (standard Defender + Hyper-V) after one UAC prompt — done.
  • On WSL2 it can't raise the UAC prompt it needs, so it will tell you to run it on the Windows side. Relay that to the user: "run rpgdev setup-firewall once in a Windows terminal (it will ask for admin)." This is the one admin-only step.
  • If WSL2 still can't reach the hub afterward, a VPN kill-switch (e.g. NordVPN) may be blocking it — tell the user to allow LAN/local in the VPN. (macOS / bare Linux: skip this whole step.)

Step 3b — Start Menu shortcut + tray (Windows / WSL2 only)

Add a Start Menu entry (Aqua-face icon) so the user has a manual launch point. No admin needed.

rpgdev setup-shortcut
  • It builds the icon and creates Start Menu\Programs\RPGDev.lnk pointing at rpgdev — self-reports the path on success. Works from WSL2 too (it talks to Windows via interop). macOS / bare Linux: skip.
  • A system-tray icon also appears automatically whenever the hub is running (launched alongside the window) — its presence tells the user the hub is up; right-click it for Open window / Return to town / Quit. There is nothing to install for the tray; this step only adds the Start Menu entry.

Step 4 — launch and verify

rpgdev            # opens the desktop window (on WSL2 it appears on the Windows host)
  • New hooks load in a new agent session — tell the user to restart Claude Code / Codex (or start a fresh session); a running session may not hot-reload.
  • After that, the next tool call makes the window react. An empty .rpgdev/hook-errors.log after a few tool calls means it's working.

Summary of what's automatic vs manual

Step Automatic (script) Manual — only when the script says it can't
install package npm i -g rpgdev —
hooks rpgdev setup --apply … existing settings file is invalid/odd → you merge per install-hooks.md
firewall (Win/WSL2) rpgdev setup-firewall on WSL2: user runs it once on the Windows side
Start Menu shortcut (Win/WSL2) rpgdev setup-shortcut —
launch rpgdev —

bare Linux has no desktop window yet — use the browser view (npm run web).