Dominus

AI-powered autonomous agent for Roblox Studio development.

Dominus connects to Roblox Studio over WebSocket, giving you a terminal-based AI assistant that can read scripts, edit code, run Luau, browse the explorer tree, manage instances, upload assets, and run tests -- all in real-time.

      ◆           ◆           ◆
     ╔█╗         ╔█╗         ╔█╗
    ╔╝ █ ╚╗     ╔╝ █ ╚╗     ╔╝ █ ╚╗
    ╚████████████████████████████████╝
         D  O  M  I  N  U  S

Features

• Autonomous AI Agent -- Plans, executes, and verifies multi-step tasks using tool calls (not just chat)
• Real-time Studio Bridge -- Bidirectional WebSocket connection to Roblox Studio via plugin
• Persistent Memory -- SQLite-backed memory that learns your project across sessions
• 15 Built-in Tools -- Read/edit scripts, run code, browse explorer, manage instances, search, upload assets, run tests
• Beautiful TUI -- Ink-powered terminal interface with explorer tree, chat, output log, and live tool indicators
• Multi-Model Support -- Use any AI model via OpenRouter (Claude, GPT-4o, Gemini, Llama, DeepSeek, etc.)
• Open Cloud Integration -- Upload images, models, and audio directly to Roblox
• Configurable Rules -- Tell Dominus what to do and what not to do with persistent rules
• StudioTestService -- Run tests directly from the terminal
• Plugin Auto-Install -- One command to install the Studio plugin

Quick Start

1. Install Dominus

# With pnpm (recommended)
pnpm add -g dominus-cli

# Or with npm
npm install -g dominus-cli

2. Set Your API Key

Get an API key from OpenRouter (free tier available):

dominus config set apiKey sk-or-v1-your-key-here

Or use an environment variable:

export OPENROUTER_API_KEY=sk-or-v1-your-key-here

3. Install the Studio Plugin

dominus install-plugin

This copies the Dominus plugin to your Roblox Studio plugins folder. Restart Studio to load it.

4. Launch Dominus

dominus

The TUI will start, open a WebSocket server on port 18088, and wait for Studio to connect. In Studio, click the Dominus > Connect button in the toolbar.

Configuration

All config is stored at ~/.dominus/config.json.

# Set your API key
dominus config set apiKey <key>

# Change the AI model
dominus config set model openai/gpt-4o

# Change the WebSocket port
dominus config set port 9090

# Set your display name
dominus config set userName Eli

# Set up Open Cloud for asset uploads
dominus config set openCloudApiKey <your-open-cloud-key>

# View all settings
dominus config list

Available Models

Any model on OpenRouter works. Popular choices:

| Model | ID | |---|---| | Claude Sonnet 4 | anthropic/claude-sonnet-4 | | GPT-4o | openai/gpt-4o | | GPT-4o Mini | openai/gpt-4o-mini | | Gemini 2.0 Flash | google/gemini-2.0-flash-001 | | DeepSeek V3 | deepseek/deepseek-chat | | Llama 3.3 70B | meta-llama/llama-3.3-70b-instruct |

Agent Rules

Tell Dominus what to do (and what NOT to do):

# Add rules
dominus rules add-do "Always use strict Luau type annotations"
dominus rules add-do "Follow Knit framework patterns"
dominus rules add-dont "Never use deprecated APIs like wait()"
dominus rules add-dont "Don't modify the DataStore schema without asking"

# View rules
dominus rules list

Rules persist across sessions at ~/.dominus/rules.json.

TUI Commands

Inside the Dominus terminal:

| Command | Description | |---|---| | (just type) | Chat with the AI agent | | /help | Show all commands | | /run <code> | Execute Luau in Studio | | /model <id> | Switch AI model | | /clear | Clear chat history | | /status | Show connection info | | /index | Re-index project scripts | | /memory | Show recalled facts |

Architecture

┌─────────────────────────────────────────────────────┐
│  Terminal                                            │
│  ┌─────────────────────────────────────────────────┐ │
│  │  Dominus TUI (Ink/React)                        │ │
│  │  ┌──────────┐ ┌───────────────────────────────┐ │ │
│  │  │ Explorer  │ │ AI Chat + Tool Indicators     │ │ │
│  │  │          │ │                               │ │ │
│  │  └──────────┘ └───────────────────────────────┘ │ │
│  │  ┌─────────────────────────────────────────────┐ │ │
│  │  │ Output Log                                  │ │ │
│  │  └─────────────────────────────────────────────┘ │ │
│  │  ┌─────────────────────────────────────────────┐ │ │
│  │  │ > Input                                     │ │ │
│  │  └─────────────────────────────────────────────┘ │ │
│  └─────────────────────────────────────────────────┘ │
│                         │                            │
│              ┌──────────┴──────────┐                 │
│              │  Agent Loop         │                 │
│              │  (Plan→Execute→     │                 │
│              │   Verify→Learn)     │                 │
│              └──────────┬──────────┘                 │
│                         │                            │
│     ┌───────────────────┼───────────────────┐        │
│     │                   │                   │        │
│  ┌──┴──┐          ┌─────┴─────┐       ┌────┴────┐   │
│  │Tools│          │  Memory   │       │   AI    │   │
│  │(15) │          │ (SQLite)  │       │Provider │   │
│  └──┬──┘          └───────────┘       └─────────┘   │
│     │                                                │
└─────┼────────────────────────────────────────────────┘
      │ WebSocket
      │
┌─────┴────────────────────────────────────────────────┐
│  Roblox Studio                                        │
│  ┌─────────────────────────────────────────────────┐  │
│  │  Dominus Plugin                                 │  │
│  │  (WS Client → Explorer, Executor, Watcher,     │  │
│  │   Properties, Reflection, TestRunner)           │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘

Studio Plugin

The plugin uses the WebSocket API introduced in Roblox Studio (October 2025):

HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, { Url = "ws://localhost:18088" })

Building with Rojo

If you have Rojo installed:

pnpm build:plugin

This creates plugin/Dominus.rbxm that you can drag into Studio.

Manual Install

dominus install-plugin

Copies the plugin Lua files directly to your Studio plugins folder.

Development

# Clone and install
git clone https://github.com/eli/dominus.git
cd dominus
pnpm install

# Run in dev mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

# Build
pnpm build

# Format
pnpm format

Tech Stack

• TypeScript + Node.js 20+ -- Runtime
• Ink 5 (React for CLI) -- Terminal UI framework
• ws -- WebSocket server
• OpenAI SDK -- AI provider (OpenRouter-compatible)
• sql.js -- SQLite in WASM (persistent memory)
• Commander -- CLI argument parsing
• Vitest -- Test runner
• tsup -- Bundler
• Rojo -- Roblox plugin builder

License

MIT