rbxl-inspect

Extract structured, LLM-readable data from Roblox .rbxl / .rbxlx place files — without Roblox Studio.

Primary use case: Feed the output to AI agents (Claude Code, etc.) so they understand how a Roblox game is structured before writing code for it.

Recommended AI workflow

# Step 1: get an overview of the game structure
rbxl-inspect game.rbxl --summary --format markdown

# Step 2: drill into a specific script by its path
rbxl-inspect game.rbxl --script "ServerScriptService.WeaponSystem.DamageHandler" --format markdown

Prerequisites

• Node.js >= 18
• Lune on your PATH — install via Cargo or download from GitHub releases:

  cargo install lune

Installation

npm install -g rbxl-inspect

Or run without installing:

npx rbxl-inspect <path>

Usage

# Inspect a single .rbxl file (outputs JSON to stdout)
rbxl-inspect game.rbxl

# Inspect all .rbxl files in a directory
rbxl-inspect ./places/

# Markdown output (great for pasting into LLM context)
rbxl-inspect game.rbxl --format markdown

# Write output files to a directory
rbxl-inspect game.rbxl --out ./reports

# Include full script source code
rbxl-inspect game.rbxl --scripts

# Extract a specific script by its dot-path (includes full source)
rbxl-inspect game.rbxl --script "ServerScriptService.Main"

# Wildcard — all scripts under a service
rbxl-inspect game.rbxl --script "ServerScriptService.*"

# Limit tree depth (useful for large places)
rbxl-inspect game.rbxl --depth 5

# Compact summary (depth 2, no source)
rbxl-inspect game.rbxl --summary

# Suppress progress messages (for piping)
rbxl-inspect game.rbxl --quiet | jq .stats

# Batch + markdown + output dir
rbxl-inspect ./places/ --format markdown --out ./reports

Flags

| Flag | Default | Description | |---|---|---| | --format <json\|markdown> | json | Output format | | --out <dir> | stdout | Write output files to directory | | --scripts | off | Include full script source code for all scripts | | --script <path> | — | Extract one script by dot-path; supports * wildcard | | --depth <n> | unlimited | Max instance tree depth | | --summary | off | Compact summary (implies --depth 2) | | --quiet | off | Suppress progress output to stderr |

Output Schema (JSON)

{
  "file": "game.rbxl",
  "inspectedAt": "2026-03-23T12:00:00Z",
  "stats": {
    "totalInstances": 1423,
    "scripts": { "server": 8, "client": 5, "module": 22 },
    "totalLinesOfCode": 4870,
    "topClasses": [["Part", 312], ["MeshPart", 98]]  // top 15, sorted by count
  },
  "services": {
    "ServerScriptService": {
      "descendantCount": 12,
      "children": [/* InstanceNode[] */]
    }
  },
  "tree": {
    "name": "DataModel",
    "className": "DataModel",
    "path": "",
    "children": [/* recursive InstanceNode[] */]
  },
  "scripts": [
    {
      "path": "ServerScriptService.Main",
      "type": "Script",          // "Script" | "LocalScript" | "ModuleScript"
      "lineCount": 45,
      "firstLine": "-- Main server entry point",
      "source": "..."            // only present with --scripts
    }
  ],
  "remotes": [
    {
      "className": "RemoteEvent",   // RemoteEvent | RemoteFunction | BindableEvent | BindableFunction
      "path": "ReplicatedStorage.Remotes.FireWeapon",
      "name": "FireWeapon"
    }
  ],
  "assetIds": ["rbxassetid://123456"],
  "dependencyGraph": {             // only present with --scripts
    "ServerScriptService.Main": ["require(script.Config)", "require(game.ReplicatedStorage.Shared)"]
  }
}

InstanceNode

{
  "name": "WeaponSystem",
  "className": "Folder",
  "path": "ServerScriptService.WeaponSystem",
  "scriptType": "ModuleScript",  // only on Script/LocalScript/ModuleScript instances
  "children": [/* InstanceNode[] — absent when at maxDepth */]
}

Example: Analyzing a game before writing code

# 1. Get a compact overview (fast, small output)
rbxl-inspect MyGame.rbxl --summary --format markdown --out ./reports

# 2. Drill into a specific script by the path shown in the overview
rbxl-inspect MyGame.rbxl --script "ServerScriptService.WeaponSystem.DamageHandler" --format markdown

# 3. Or pull all scripts under a service at once
rbxl-inspect MyGame.rbxl --script "ReplicatedStorage.*" --format markdown

# Then feed the output to Claude Code:
# "Here's the structure of my Roblox game and the DamageHandler script.
#  I want to add falloff damage — here's how the system currently works..."

Architecture

rbxl-inspect (TypeScript CLI)
  └── spawns: lune run lune/extract.luau -- <file> <flags-json>
       └── uses Lune's roblox library to deserialize the .rbxl file
       └── outputs JSON to stdout
  └── parses JSON output
  └── formats as JSON or Markdown

The Lune script (lune/extract.luau) handles all Roblox file parsing. The TypeScript layer handles CLI ergonomics, formatting, and batch mode.

Development

npm install
npm run build       # compile TypeScript
npm run dev         # watch mode

# Test the Lune script directly
lune run lune/extract.luau -- test/fixtures/minimal.rbxlx '{}'
lune run lune/extract.luau -- test/fixtures/minimal.rbxlx '{"scripts":true}'

# Test the full CLI
node dist/cli.js test/fixtures/minimal.rbxlx
node dist/cli.js test/fixtures/minimal.rbxlx --format markdown
node dist/cli.js test/fixtures/minimal.rbxlx --scripts