Roforge Cli

CI npm version license RoForge Pro

A local Claude-Code-style AI agent for Roblox Studio. Runs on your machine, talks to Roblox Studio, uses your own API key (BYOK), and has zero backend in the core — free of subscriptions, free of credit meters, free of middlemen.

┌─────────────────────────── your machine ───────────────────────────┐
│                                                                    │
│  roforge (CLI/TUI)          Roblox Studio                          │
│  ┌──────────────────┐       ┌──────────────────────────────────┐  │
│  │ streaming agent  │  MCP  │  built-in MCP server (beta)      │  │
│  │ loop (Luau-aware)├──────►│  …or the RoForge Bridge plugin   │  │
│  │                  │       │  (forge_* tools, polling)        │  │
│  │ project tools    │       └──────────────────────────────────┘  │
│  │  read/edit/run   │                                             │
│  │ web + roblox API │                                             │
│  └────────┬─────────                                             │
└───────────┼────────────────────────────────────────────────────────┘
            │  direct HTTPS (your key)
            ▼
  api.anthropic.com · api.openai.com · generativelanguage.googleapis.com
  api.groq.com · openrouter.ai   (auto-routed, free tiers first)

Your key goes only to the model provider. Everything else — Studio traffic, project files, web search — stays on your machine.

What it does

• Edits your Rojo project like Claude Code edits a repo: project_tree, project_read, project_write, project_edit, project_search, project_run (rojo builds, tests), luau_analyze — with approval gates on destructive actions.
• Sees the viewport (vision): forge_viewport captures the Studio 3D viewport as a real PNG and shows it to a vision-capable model — ask "does that part look centered?" and it will actually look. (Bridge plugin; Studio's built-in MCP screenshots reach the model too.)
• Edits are undoable: forge_checkpoint marks the Studio undo history before a destructive batch and forge_undo rolls it back — so the agent can make changes without breaking your place. (ChangeHistoryService.)
• Drives live Studio: read the DataModel, read/write scripts, create/delete instances, run Luau, inspect/set individual properties and attributes, control the selection, screenshots, find instances (name/class), bulk-create a whole structure in one approval, snapshot/diff the hierarchy (what changed), and export subtrees as JSON — via Studio's built-in MCP server (beta, official) or the RoForge Bridge plugin (our fallback).
• Knows Roblox: web search, URL fetch, Roblox game/user lookups — all local, no backend.
• Streams: real token streaming in the terminal (the in-Studio plugin couldn't — that's why the brain moved to a local process).
• Shows its work: every tool call is printed with its result; per-turn token + estimated cost footer.

Quick start

Requirements: Node.js ≥ 18.17 (no npm dependencies).

npm i -g roforge-cli               # install (or: git clone this repo → cd cli)
roforge login --provider gemini    # or groq / openrouter / anthropic / openai
roforge                            # interactive TUI in your project directory

Also published on GitHub Packages as @hacvilke/roforge-cli (any GitHub token with read:packages works):

npm config set @hacvilke:registry https://npm.pkg.github.com
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc
npm i -g @hacvilke/roforge-cli

No paid API yet? The free tiers work out of the box: a free Gemini key (aistudio.google.com, ~1,500 req/day, no card), Groq (console.groq.com), or an OpenRouter :free model. provider: "auto" (default) picks the first key you have — free tiers first — at $0 cost. roforge providers shows what's set.

One-shot:

node bin/roforge.js chat -m "Summarize this project and list the scripts that talk to HttpService"

Connecting Studio (pick one):

1. Built-in MCP (recommended). Studio → File → Studio Settings → Beta Features → enable MCP Server (listens on localhost:3004). RoForge detects it automatically — /studio in the TUI shows the status.
2. RoForge Bridge plugin (not in the Roblox Toolbox — it ships with roforge). Install, then paste the token:

   roforge install-plugin        # copies the bundled .rbxm into Studio's plugins folder
   roforge studio                # keeps the bridge running, prints the token
   # in Studio: File → Plugins (RoForge Bridge is listed) → paste token → Save
   

   From a git clone instead: node scripts/install-plugin.mjs bridge, or Studio → Manage Plugins → Install File… with studio-bridge/dist/RoForgeBridge.rbxm (prebuilt, committed).

Commands: roforge (TUI) · chat -m "…" · studio · tools · install-plugin · pro (license status) · login --provider <p> · providers · analyze <file…> · config [set k v] · version. Full usage: docs/CLI.md.

Repository layout

cli/           MIT — the local agent (Node, zero deps)
  bin/roforge.js          CLI entry (TUI / chat / studio / pro / install-plugin / tools / login / analyze)
  src/providers/          anthropic · openai · gemini · groq · openrouter (SSE) adapters
  src/mcp.js              MCP Streamable-HTTP client (talks to Studio's server)
  src/bridge/             local loopback bridge server (polling protocol)
  src/tools/              web, roblox, project, studio tool factories
  src/agent.js            the agent loop
  src/tui/                terminal UI (ANSI, zero deps)
  test/                   94 tests incl. full agent loop + provider routing + vision on both tiers
  dist/                   prebuilt .rbxm plugins (bundled into the npm package)
  demo/e2e-demo.mjs       offline end-to-end demo
studio-bridge/ MIT — thin Studio plugin (Luau) that polls the bridge
  src/Root/Bridge/        Bridge loop, LocalTools, ExtraTools, Viewport, PngEncoder, Pro
  test/                   PNG encoder + Pro entitlement validation (runs under `luau`)
hq/          MIT — the RoForge HQ experience starter (where RoForge Pro is bought)
client/        MIT — (v0.1) full in-Studio chat plugin, still works standalone
server/        Apache-2.0 — (v0.1) optional hosted tool backend, not required
scripts/       install-plugin.mjs (copies a built .rbxm into your OS plugins folder)
docs/          architecture, CLI, bridge protocol, tool spec, security, monetization
.github/       CI: node tests + e2e demo + PNG validate + Pro validate + luau-analyze + rojo builds

Why local-first (and what that buys you)

• Free core: no backend to run or pay for; the only cost is your model usage.
• Private: chat, key, and project files never touch any third party.
• Streaming: a local process has real HTTP/SSE; the in-Studio plugin could only do whole-response requests.
• Portable: roforge works in a repo (Rojo project) with no Studio open, and gains Studio superpowers when Studio is.

The old in-Studio plugin (client/) and the hosted backend (server/) still work as standalone modes — the local CLI is now the primary surface.

RoForge Pro

RoForge is open-core: the entire agent, all 25 forge_* Studio tools, and the Pro entitlement check are MIT. RoForge Pro is a one-time Robux game pass (~999 R$) that raises limits and unlocks advanced features. No account, no subscription — ownership is checked in Studio via MarketplaceService, and the free build keeps working for non-Pro users.

Check your status: roforge pro (attaches to a running roforge studio bridge, or starts a short-lived one). The plugin dock also shows a FREE/PRO badge and lets you paste your Pro Game Pass ID / Pro Dev Product ID so ownership checks work.

Get Pro: create the pass in the RoForge HQ experience (hq/ has the starter place + step-by-step), then buy it there — your Studio session detects it automatically. Licensing boundary: LICENSE-PRO.md · monetization: docs/MONETIZATION.md.

Status

MVP complete and tested: 94/94 CLI tests (incl. full agent loops against mock providers and the vision image contract), 21/21 backend tests, 35/35 Pro entitlement checks, pixel-validated PNG encoder with a from-scratch RFC 1951 DEFLATE compressor (1024×576 viewport → 103KB, 23× smaller than stored blocks), 5 model providers with free-tier auto-routing (Gemini / Groq / OpenRouter / Anthropic / OpenAI — roforge providers), Luau analyzer-clean plugins, Rojo-built .rbxm artifacts, offline e2e demo, GitHub Actions CI. Latest: viewport vision on both tiers (bridge forge_viewport and Studio's MCP screenshots — the model actually sees Studio), ChangeHistoryService undo checkpoints, find/bulk-create/snapshot/diff/export/import Studio tools (29 forge_* total — forge_import re-applies an export JSON, forge_pro reports the license, and the four Pro feature seams forge_pro_features / forge_cloud_snapshot / forge_cloud_restore / forge_team_share delegate to the closed Pro module when it is installed — the open plugin itself only contains the MIT ProModuleLoader seam), multi-block DEFLATE (streams

64 KB now inflate byte-exact, with per-block dynamic/stored choice), property-level forge_diff, streaming Markdown + expandable tool output (/out) in the TUI, real deflate, multi-provider + free tiers, the published roforge-cli npm package (zero deps — npm i -g roforge-cli), the Pro pass-gate (free/Pro limits enforced in the plugin, 60-check Luau test suite), and a strict declarative plugin system (JSON tool specs only — no code field, so a plugin can't contain malicious intent by construction). Next: hosted Pro backend deployment, Deflate speed tuning. See PROGRESS.md and docs/MONETIZATION.md.

License

cli/, studio-bridge/, hq/, client/ — MIT · server/ — Apache-2.0

Closed-source RoForge Pro components (when distributed) are separately licensed — see LICENSE-PRO.md. Contributing: CONTRIBUTING.md.