🧭 Rojo Compass — Project-Aware Roblox Sync for Autonomous Agents

A semantic filesystem bridge between your Studio place and your local codebase, built for machines that read, reason, and refactor.

Rojo Compass is a sibling project to roxo-mcp, but it takes a different philosophical stance: instead of treating the filesystem as a passive mirror of a Studio session, it treats the filesystem as a living map — one that agents can annotate, query, and reason about in natural language. Where roxo-mcp focuses on the tight transport loop between MCP clients and Roblox Studio, Rojo Compass focuses on the meaning layer that sits on top of that transport: project topology, dependency graphs, symbol indices, and intent records that survive across sessions.

If roxo-mcp is the nervous system, Rojo Compass is the cognitive map.

---

🌌 The Idea Behind the Name

Rojo (the well-loved Roblox filesystem synchronizer) gives you a two-way bridge. Compass gives you orientation. A compass doesn't move the ship; it tells you where you are relative to everything else. Rojo Compass does exactly that for AI agents operating inside a Roblox project: it answers questions like "where does this RemoteEvent actually get consumed?", "which ModuleScripts are orphaned?", "what changed between the last two agent sessions?", and "which parts of this place graph are safe to refactor without touching the UI layer?"

The repository ships three cooperating pieces:

1. A semantic indexer that walks your Rojo project tree and produces a queryable graph of scripts, instances, services, and cross-references.
2. A status & query daemon that exposes this graph over a small local protocol — designed to be MCP-adjacent but protocol-agnostic so any agent runtime can talk to it.
3. A Studio-side observer plugin that connects to the daemon on its own initiative, feeding live instance state back into the index without any manual pairing step.

Together, these three pieces let an autonomous agent understand what the project is, not just what files exist.

---

✨ What Makes This Different

Most Roblox tooling assumes a human is at the keyboard. The human remembers that ReplicatedStorage/Shared/Net.lua is the network wrapper, that ServerScriptService/Services/ holds all the service singletons, that the PlayerData module is a leaf dependency. Agents don't have that intuition unless someone encodes it.

Rojo Compass encodes it — automatically, incrementally, and in a form both humans and machines can read.

• Instead of parsing Luau with regexes, it builds a real symbol table using a tree-sitter grammar, so re-exports, aliases, and dynamic require calls are tracked with reasonable fidelity.
• Instead of assuming a fixed project layout, it learns the layout by observing which folders hold services, which hold components, and which hold dead code.
• Instead of a one-shot snapshot, it maintains a temporal index so agents can ask "what changed since I last looked?" and get a meaningful answer.

---

🧩 Feature Matrix