gamedev-log-analyzer

gamedev-log-analyzer — game-engine/build log analysis (CLI)

Read logs through the gamedev-log CLI, never cat/grep/Get-Content the raw file — these logs are routinely tens of MB and will flood the context. The CLI parses → classifies → deduplicates → returns a compact, token-capped summary (often ~99% smaller than the raw log).

Format coverage: Unreal runtime + MSVC/UBT/MSBuild/Unity-C# build + JSONL are live-verified (JSONL on a real UE AIMovementDebug.jsonl). For JSONL, fields also extracts Key=value / Key=(x,y,z) from inside the message plus top-level keys, so per-frame scalar tracking over a --window works. Unity-deep, Godot, Python-logging, and bracketed-level parsing are best-effort from public docs and NOT verified against a specific app's real logs — say so if you report results for those, and run gamedev-log learnings to see what went unparsed.

How to run it

Invoke via Bash using the plugin-root absolute path (no PATH/setup needed; pure Node, no deps):

node "${CLAUDE_PLUGIN_ROOT}/server/cli.js" <command> [--flags]

Quote every path argument (Windows paths/spaces). --help lists everything.

Commands

• detect — find editor logs (newest first). --projectPath <dir> (UE: scans <dir>/Saved/Logs, one subdir deep; Unity: Editor.log). Run this first if you don't have a path.
• summary — severity counts + top categories, no message bodies. --path | --projectPath.
• search — parse + dedup into templated groups with ×count + locations, severity-sorted, capped.
  • --severityMin Error|Warning|Display (default Warning) · --query <substr> · --category <Cat>
  • --file <pathfrag> · --groupBy template|callsite|code (callsite = roll up by file:line, best for "which callsite floods the log"; code = roll up by diagnostic code like C4996/LNK2019, collapsing a noisy build to one line per code) · --maxGroups N
• diff — compare two logs, emit ONLY the delta (new / gone / count-changed groups; unchanged omitted). --pathA <before> --pathB <after>, or omit both to auto-pick the two newest detected logs. Same filters as search plus --minDelta N. Token-cheap "what changed since last run?".
• locate — jump list: just the distinct file:line of matched entries (no message bodies), ranked by severity then count. --severityMin Error (default) · --basename (strip to filename, for Rider's name search) · --query --category --file --max. The compact handoff for opening source.
• fields — pull just decisive scalars from dense per-frame trace logs into a compact table. --fields Pawn,Alpha,ts,Pos.x,step:Pos,d:Yaw (forms: Key, Key.x|.y|.z, Key.Y|.P|.R, ts, dts, d:Key, step:Key) · --query · --window t0,t1 · --max N. Biggest win on per-frame logs. Add --stats to collapse to per-column min/max/avg/first/last/Δ (one line per field) instead of rows — use it for "what's the range/trend of X over this window?" (even fewer tokens than the table).
• tail — last N raw lines (escape hatch). --lines N.
• setup / config — persist/show settings (~/.gamedev-log-analyzer/config.json). Keys: --projectPath --logPath --logMaxBytes --maxGroups --maxLineChars.
• learnings / learnings-reset — local sanitized parse-coverage report + top unparsed line shapes (new-parser candidates). See Growing format coverage below; a low-coverage file also auto-nudges.
• savings / savings-reset — local cumulative report of how many tokens you've saved vs dumping raw logs into context. Each analysis also appends a one-line ✓ Saved ~N tokens (M× smaller) for big logs.
• enforce <block|warn|off> (or no arg = status) — log-read enforcement. A PreToolUse hook intercepts raw Bash log reads (grep/tail/cat/… over .log/.jsonl/Logs) and unbounded Reads of large (≥ 200 KB) logs, steering them here. A sliced Read (offset/limit) always passes — that's the one-step escape when you truly need raw bytes or when a format parses poorly. warn (default) allows + nudges; block denies + nudges; off disables. Env: GDLOG_ENFORCE. If a user hits the block and genuinely wants raw bytes, tell them to re-Read with offset/limit, or gamedev-log enforce warn|off.