Skip to content

install-hooks.md

Latest commit

 

History

History
95 lines (75 loc) · 5.27 KB

install-hooks.md

File metadata and controls

95 lines (75 loc) · 5.27 KB

RPGDev hook setup — recipe for an AI agent

This document is written for an AI coding agent (Claude Code, Codex, …). If a user asks you to "set up RPGDev hooks", follow these steps exactly. RPGDev itself never edits the user's settings — you apply the change, carefully, in front of the user.

RPGDev turns the user's coding-agent hook events (every tool call, prompt, subagent, turn end) into a small desktop RPG. To make that happen, the user's agent must call rpgdev-hook on each hook event. Your job is to add those hook entries to the right settings file without breaking anything.

Prerequisite

rpgdev must be installed on disk (the hook runs a file from the package on every tool call):

npm install -g rpgdev      # or: clone the repo and run from source

Step 1 — ask the user two things

  1. Which agent to wire up: Claude Code, Codex, or both.
  2. Scope: this project only (default) or the whole machine (home-level config).

Step 2 — get the correct config (do not hand-write it)

Run the setup command for the chosen provider and scope, and read its output. It prints the exact config with the real absolute paths for this machine and the correct command form per platform — so you never have to guess paths, event names, or the Windows command form.

rpgdev setup --claude            # Claude Code, this project
rpgdev setup --codex             # Codex, this project
rpgdev setup --all               # both
rpgdev setup --claude --user     # Claude Code, home-level (~)
rpgdev setup --json --claude     # raw JSON only

The output tells you the exact target file path and the JSON to merge. Write to that path verbatim — the file differs by scope (this trips people up):

Scope Claude Code Codex
this project (default) <project>/.claude/settings.local.json <project>/.codex/hooks.json
user-global (--user) ~/.claude/settings.json ~/.codex/hooks.json

Important: for user-global Claude hooks the file is ~/.claude/settings.json — NOT ~/.claude/settings.local.json. settings.local.json only exists at the project level; a user-level settings.local.json is never read by Claude Code, so hooks placed there are silently ignored. (Users typically already have hooks/permissions in ~/.claude/settings.json, so merge carefully per Step 3.)

Step 3 — merge it safely (these rules are mandatory)

Read the target file (it may already contain the user's own settings). Then:

  • Touch only .hooks. Never modify or drop any other key — permissions, env, model, mcpServers, statusLine, or anything else stays exactly as it was.
  • Keep the user's existing hooks. For each event, append the rpgdev entry to the existing array; do not replace the user's own hooks for that event.
  • Idempotent. Each rpgdev entry carries "_rpgdev": "rpgdev". If an entry with that marker already exists for an event, update its path in place instead of adding a duplicate. Re-running setup after an npm update (which may move the install path) should refresh the path, not duplicate it.
  • Never overwrite invalid JSON. If the existing file is not valid JSON, stop and tell the user — do not replace it.
  • Back up first. Before writing, copy the existing file to a backup (e.g. settings.local.json.rpgdev-bak). Do not overwrite an existing backup.
  • Write atomically if you can (write a temp file, then rename over the target) so a crash can't truncate the user's settings.
  • Show the user the diff before/after writing.

Step 4 — confirm it works

  • Claude Code loads hooks when a session starts. A brand-new session picks them up automatically; an already-running session may not hot-reload mid-session — restart it (or start a fresh session). After that, the next tool call makes the RPGDev window react.
  • Codex may likewise need the session restarted to pick up new hooks.
  • Start the window if it isn't open: rpgdev (macOS / Windows; on WSL2 it appears on the Windows host).
  • Windows / WSL2: while the hub runs, a system-tray icon (the Aqua spirit's face) sits in the notification area — its presence means the hub is up, and it disappears when the hub stops. Windows hides new tray icons in the overflow (^) by default, so look there. Right-click it to open the window, return to town, or quit (which stops the hub). Optionally add a Start Menu entry: rpgdev setup-shortcut (no admin needed; works from WSL2 too).
  • If a hook can't reach the server it logs to .rpgdev/hook-errors.log and stderr (it never fails silently). An empty hook-errors.log after a few tool calls means it's working.

Notes

  • The generated command uses an absolute path to node + the installed scripts/rpg-hook.mjs, so it works without the package being on PATH and avoids the Windows .cmd-shim pitfall (Claude's exec-form hooks don't go through a shell). Run rpgdev setup in the same environment the agent runs in (native Windows vs WSL2) so the captured paths match.
  • Codex cannot report tool failures via hooks, so the Codex config has no failure events (that's expected, not a bug).
  • Windows + Codex only: if the inline command doesn't spawn on your machine, re-run with rpgdev setup --codex --codex-cmd-wrap to wrap it in cmd /c.