# Rojo projects

> Link your Rojo project folder in the RoGenie Bridge (Windows). RoGenie reads your files, edits them once you allow it, checks that each change reached Studio, backs up every file it changes, and never edits Rojo's scripts in Studio.

If [Rojo](https://rojo.space/) syncs your place, the files on your PC are the real copy of every script Rojo manages: `rojo serve` overwrites a change made to them in Studio. Link your project folder in the [RoGenie Bridge](https://rogenie.ai/docs/bridge) and RoGenie works the way your project does. It reads those scripts from your files, searches your whole project, knows which instances Rojo makes from which file, and never changes a script Rojo manages inside Studio.

Once you **allow edits** for the folder and file editing is on for your account (it is turning on gradually), RoGenie edits your repo's files with the same tools it uses on Studio scripts. Your own `rojo serve` syncs them into Studio, RoGenie checks that each change reached the Studio you have open, it backs up every file it changes, and reverting a turn puts the files back.

> **Note**
> Linking a folder needs **Windows**, the RoGenie Bridge **2.5.0 or newer** (it updates itself) and the RoGenie plugin **1.1.152 or newer** (it updates itself too). Mac is not supported yet. A folder starts **read only**: RoGenie edits files only after you choose **Allow edits** for it in the Bridge window, and file editing is being turned on for accounts gradually. Until then, for a script Rojo manages RoGenie gives you the change as a diff to apply.

## Link your project folder

1. Open the **RoGenie Bridge** window (the RoGenie icon in the tray), or press **Open the Bridge window** in the app's **Project** menu.
2. Under **Project folders**, click **Link folder…**.
3. Windows opens its own folder window. Pick your project's folder: the one with `default.project.json` in it.
4. Windows asks you to confirm. The question shows the folder, the Rojo project files and Git repository it found, and that RoGenie can read but not change the files. Click **Yes**.
5. Open your place in Studio. In the app, open the **Project** menu next to the Studio menu and click **Link to this place**.

RoGenie then lists what Rojo manages, for example `ReplicatedStorage.Shared ← src/shared`, and checks every script there against the copy in Studio. If your project's `servePlaceIds` include the place you have open, RoGenie offers the link by itself: a message with a **Link** button. It never links a folder without your click, and an unpublished place always needs one.

A link belongs to the **place**, so every chat about that place follows it. A chat keeps the folder it used too, so RoGenie can still read your files while Studio is closed. If you open a different place in that chat, the folder doesn't come along: that place's own link applies, or none.

## Let RoGenie edit your files

In the Bridge window, next to the folder, click **Allow edits**. Windows asks you to confirm in its own message box (a web page cannot click it). The folder then reads **Can edit**. **Make read-only** takes edits away at once, and so do **Pause** and **Unlink**.

From then on, when RoGenie changes a script Rojo manages, it changes the **file**:

- **The same edits as in Studio.** Anchored edits, symbol edits, line-range edits, whole-script writes and find and replace run through the same editor RoGenie uses on Studio scripts: the same anchor matching, the same ambiguity checks, and the same compile check before anything is saved. A change that would break a script that compiles today is refused, and nothing is written.
- **Only the lines it changed.** Each file keeps its own line endings (CRLF or LF) and its BOM, so `git diff` shows only the edited lines. A file that mixes CRLF and LF is not edited unless the whole file is rewritten on purpose.
- **Your saves win.** RoGenie edits the version it read. If you saved the file in VS Code (or anything else) since, the edit is refused as a conflict and your save stays; RoGenie reads the file again first. It only sees what is saved on disk: a change you have not saved in your editor is invisible to it.
- **New scripts and instances become files** named by your project's rules: a Script is `Name.server.luau`, a LocalScript `Name.client.luau` (with `emitLegacyScripts` false, a Script with RunContext Client is `Name.client.luau`, and a LocalScript cannot be made from a file), a ModuleScript `Name.luau`, using the extension your project already uses. A RunContext or Disabled the file name cannot say (a Script with RunContext Client when `emitLegacyScripts` is true, RunContext Legacy when it is false, or a disabled script) goes into a `Name.meta.json` beside it. A module that gets its first child moves to `Name/init.luau`, and its `Name.meta.json` to `Name/init.meta.json`; a LocalScript made by a `*.local.luau` rule cannot get children, because Rojo has no folder form for it. A Folder is made as a folder (holding a `.gitkeep`, or an `init.meta.json` for its properties), so you can put things in it next. A RemoteEvent, RemoteFunction, UnreliableRemoteEvent, BindableEvent, BindableFunction, Configuration or a Value object is made as `Name.model.json` (a Value object's `Value` must match its class). Other classes are refused: build them outside Rojo's paths, or in a model file you add. A name Rojo would read as part of the file name, such as `init` or a name ending in `.server`, `.client`, `.meta` or `.luau`, is refused, because the instance would come back with another name or class.
- **Renames and moves move the file**, keeping its `.server` / `.client` suffix, and its `Name.meta.json` goes with it, so its properties and attributes stay. Moving something out of the repo's paths, or into them from Studio, is refused. A file your project file names itself in a `$path` (for example `"ClientStarter": {"$path": "src/.../ClientStarter.client.lua"}`) is never renamed, moved, deleted or given children: its name and place come from the project file, so change `default.project.json` first. A rename does not rewrite references to the old name in other files: RoGenie says so, and fixes them with edits.
- **Deleting an instance deletes its file**, and its `Name.meta.json`. A folder is deleted file by file.
- **Properties, attributes and tags** of an instance Rojo manages are not changed in Studio: RoGenie edits the `Name.meta.json` beside the file instead.
- **Any other file of the project**, such as `README.md`, `wally.toml`, `default.project.json` or `.rogenie/notes.md`, can be changed by its path (the **Project Folder (edit)** tool). Overwriting a whole file needs the version RoGenie read.

Everything else works in Studio as before: Workspace, UI you build in Studio, Lighting, and services your project doesn't map.

### Did the change reach Studio?

After every file change, RoGenie reads the script back from Studio (what Studio actually holds, not an open editor's draft) for up to 6 seconds, and asks your PC whether `rojo serve` is serving this project. Each result says which side was written, for example `Saved src/shared/Util.luau; Studio: landed in 0.4 s`, and the chat shows the file, the diff and the state:

| State | What it means |
|---|---|
| **In Studio** | Studio has the new text. |
| **Not in Studio yet** | `rojo serve` is serving this project, but Studio has not changed: the Rojo plugin in Studio is probably not connected to it. |
| **rojo serve off** | `rojo serve` is not running on your PC. |
| **Other project** / **other place** | `rojo serve` is serving another project, or the project's `servePlaceIds` don't include the place open in Studio. |
| **Studio not checked** | Studio is not connected to RoGenie, so it could not check. Or the change isn't a script's code (a `.model.json`, a `.txt` or `.json` value, a `.meta.json` or the project file): RoGenie reads back only scripts' source, so look in Studio once `rojo serve` syncs it. |
| **Studio not checked: plugin update** | Studio is connected, but its RoGenie plugin is older than 1.1.152: reload it in Studio to update it. |
| **In Studio, draft differs** | Studio has the change, but a script open there has an unsaved draft that differs. |

A change that has not reached Studio stays **pending**: the file is saved, RoGenie does not write it again, it checks again on its next step, and it tells you what to do (start `rojo serve`, connect the Rojo plugin). A file stops being pending once it no longer holds RoGenie's change (you reverted the turn, or saved your own version), and after 6 hours. The **Project** chip counts pending files. Before a playtest, RoGenie waits up to 5 seconds for pending files and says when Studio is running old code. Errors in a playtest name the file and line in your repo. A plan step that changes files can require that its files reached Studio before it counts as done, and RoGenie never says a change works in Studio while it is pending.

If your project folder is on one PC and Studio runs on another, Studio never gets the change from this PC: the files stay saved and the results say they are not in Studio.

### Backups and revert

Every file RoGenie changes, creates, moves or deletes is backed up by the Bridge on your PC, per turn, before it changes it. A change to several files at once is all or nothing: if one file fails, the others are put back, and if the Bridge stops in the middle, it finishes or undoes that change when it starts again. Backups are kept 14 days (up to 1 GB). **Open backups** in the Bridge window shows them.

[Reverting a turn](https://rogenie.ai/docs/revert) restores its files together with its Studio changes, and while `rojo serve` is running Rojo syncs the restored files into Studio (RoGenie does not check that part). A file you changed after that turn is left as it is and named, so your own edits are never lost. A turn's files can be reverted only through the linked folder with edits allowed: after **Unlink** (a link made again is a new link) or **Make read-only**, earlier turns' file changes can no longer be reverted from the chat, but the backups stay in **Open backups**.

## What RoGenie does in a linked place

- **Reads your files.** When RoGenie reads, searches or lists a script Rojo manages, it reads the file in your folder, not Studio's copy. It sees the same line numbers as Studio and the same version check (`source_hash`) for files saved with LF line endings and no BOM. It says when Studio's copy differs (for example, `rojo serve` has not synced it yet). A search covers your files and the rest of the place, and RoGenie never counts a Studio copy of a file twice.
- **Reads the rest of your project.** RoGenie can read, search and list any file in the folder, such as `README.md`, `wally.toml`, `default.project.json` or your tests, by its path.
- **Never edits Rojo's scripts in Studio.** RoGenie doesn't edit, create, rename, move or delete anything Rojo manages in Studio. With edits allowed, it changes the file instead; without, it names the file the change belongs in and gives you the change as a diff, and the [IDE](https://rogenie.ai/docs/ide) refuses to save those scripts. The RoGenie plugin refuses those Studio edits too, as a second check.
- **Warns about Luau that changes Rojo's scripts.** When Luau code RoGenie runs in Studio sets the source of a script Rojo manages (or adds a script under its paths), the result says Rojo will overwrite it, and RoGenie makes the change in the file instead.
- **Checks `rojo serve`.** RoGenie asks your PC whether `rojo serve` is running for this project (on the project's `servePort`, or Rojo's default 34872, on your own PC only) and says so if it isn't, or if it serves another project or doesn't list this place.
- **Learns your conventions.** RoGenie reads your project's `AGENTS.md`, `CLAUDE.md` and `.luaurc`, and `.rogenie/notes.md`, into the chat, marked as your project's text. They describe the project; they can't change RoGenie's own rules.

Packages in `Packages/`, `DevPackages/` and `ServerPackages/` are listed as installed packages, and RoGenie never changes them.

When a place has a linked folder, the pasted project file in **Settings › Memory › Rojo project** is not used for it: the folder's own mapping replaces it.

## How RoGenie knows what Rojo manages

The Bridge reads your project file the way Rojo 7.7 does: the project tree (`$className`, `$path`, `$ignoreUnknownInstances`), folders, `init.luau` and `init.meta.json`, the script suffixes (`.server.luau`, `.client.luau`, `.plugin.luau`) and `emitLegacyScripts`, `.model.json` and `.rbxm` models, `.json`, `.toml`, `.txt` and `.csv` files, nested `default.project.json` files (Wally packages), `globIgnorePaths` and simple `syncRules`. Instance names with dots stay whole.

If your project uses something the Bridge cannot read, or a `sourcemap.json` newer than the project file maps an instance differently, RoGenie says the map is **partial** and treats those instances as Rojo's. It never guesses that one is free to edit in Studio, and it does not edit a file whose mapping is uncertain except by its path.

## Privacy and safety

- The Bridge reads **only folders you link**, and only inside them, and changes files only in folders where you allowed edits. You pick each folder in Windows' own folder window and confirm it, and allowing edits, in a Windows message box. No web page, chat or message from RoGenie's servers can link a folder, name one, or allow edits.
- It never reads `.env` files (and `*.env`, `.envrc`, `.dev.vars`), keys and credentials (`.pem`, `.key`, `id_rsa`, `credentials.json`, `credentials`, `_netrc`, `.pgpass`, `*.tfvars`, keystores and the like), anything in a `secrets`, `.aws`, `.docker` or `.ssh` folder, `.npmrc`, `.git-credentials`, Git's own `.git` folder, binary files, files over 2 MB, or anything you list in a `.rogenieignore` file in the folder (same rules as `.gitignore`; save it as UTF-8 or UTF-16 text), and it never writes there either. If a `.rogenieignore` exists but can't be read (another program holds it, it is a link, or it is not text), the Bridge reads and changes nothing in that folder until it can. RoGenie never adds a `$path` to the project file that would bring any of those files into Studio, or a file holding text that looks like a key (a file your `syncRules` sync included, every file under the `$path` when a rule's glob holds a `[...]` class or a backslash, and every file under every `$path` when RoGenie changes the `syncRules` themselves, whatever the new rule matches; a binary `.rbxm` model, which the Bridge can't check, is left for you to map). Text that looks like an API key or a Roblox cookie is replaced with `[REDACTED]` before the agent sees it, searches run over that redacted text, and RoGenie never edits a file that holds such text.
- It only writes text files RoGenie edits (`.luau`, `.lua`, `.json`, `.md`, `.txt`, `.csv`, `wally.toml`, `selene.toml`, `stylua.toml`, `.luaurc`, `.gitignore`), and a file Rojo reads (`.json`, `.model.json`, `.meta.json`, `.csv`, TOML) only when Rojo can read it, with properties the class has, and the same goes for the project file's own `$properties`, for a rename or move that changes what a `.meta.json` describes (a `Job.server.luau` renamed to `Job.luau` while `Job.meta.json` sets `Disabled`), and for a change to what a project node's `$path` makes (an `init.luau` created in a folder whose node names a `$className`, a `.model.json` turned from a Part into a Model while the node sets `Anchored`; a `$className` beside a `$path` builds only when that path makes a plain Folder, and a nested project whose tree has no `$className` is whatever its own `$path` makes): one bad file stops `rojo build` for the whole project. A service your project maps by its name alone (`"ReplicatedStorage": {"$path": "src/shared"}`) stays that service: RoGenie won't create an init file, an `init.meta.json` naming a class or a project file in that folder, which would put a script or another class in place of the service. Put such a file in a folder under it instead. A file your `syncRules` have Rojo read as JSON, TOML or a model is checked as that, whatever its name, and a new `syncRules` glob Rojo can't parse, or one with a backslash (a folder on Windows, an escape elsewhere), is refused, as is a new `$path` to a file or folder that isn't there (RoGenie writes a file there in the same change, or makes it `{"optional": ...}`). A new `$path` has the files under it checked the same way before Rojo reads them: an `.rbxmx` model must be one Rojo reads and can write to an `.rbxl` place as well as an `.rbxlx` one (one instance per file, as Studio's Save to File writes when you save a single object, so group several in a Model first; and each value of the type its property has, as Studio saves it), and a nested project you map for the first time must be a project file Rojo reads, every key and node of it, and has the `$properties` and `$attributes` of its nodes checked against the classes they make. A typed whole number (`{"Int32": ...}`, `{"Int64": ...}`, a `UDim` offset) must fit the integer Rojo reads it as and be written as one (`0`, never `-0`, which Rojo reads as a fraction), a plain number for a whole-number property must be a whole number in its range, a `Float32` must fit one, and a part's `Color` takes components from 0 to 1, or Rojo would build another value into the place. `{"Color3uint8": ...}` is written only for a part's `Color`, the one color an `.rbxl` place keeps that way: anywhere else give `[r, g, b]` from 0 to 1. Every node of a nested project you map for the first time needs a class Rojo can give it (a `$className`, a `$path` that exists, or a service's own name), and a property Rojo's database doesn't know keeps one value type across every model file in the place, a binary `.rbxm` included (the Bridge looks inside one only for its class and property names and their value types). A file Rojo already reads (a `.txt` StringValue, a `.json` ModuleScript) that a change would have Rojo read as a project or a model is left as it is when it holds a value that looks like a secret. It doesn't write YAML, which it can't check that way: ask for the data as `.json`, which Rojo turns into the same ModuleScript. It never writes a dot-folder or dotfile (where CI services, Git hooks, hook runners, editors and coding agents keep the settings that run programs: `.git`, `.github`, `.vscode`, `.claude`, `.aider.conf.yml`, `.lintstagedrc` and the like) except `.luaurc`, `.gitignore`, `.gitkeep`, `.stylua.toml`, `.darklua.json`, `.cursor/rules/*.md` and `.rogenie/notes.md`. Nor does it write other CI and task files (`Taskfile.yml`, `bitrise.yml`, every lefthook config name, in any folder), build configs an editor or a common command runs (`CMakeLists.txt`, which Visual Studio and CLion configure when they open the folder, `CMakePresets.json`, `cdk.json`, `nodemon.json`), the `lune` folder, toolchain files (`rokit.toml`, `aftman.toml`, `foreman.toml`, `pesde.toml`), `package.json` or programs. RoGenie never changes `servePort`, `servePlaceIds`, `globIgnorePaths` or the like in a project file: they decide what Rojo serves and where, so you make that change yourself.
- Each write goes through a temporary file (named `.~rogenie-….tmp`, which Rojo maps to nothing) and replaces the file in one step, so a crash leaves the old file or the new one, never half of it.
- A turn changes at most 200 files and 8 MB, and deleting more than 25 existing files in one turn stops and needs you. A whole-file rewrite that would drop more than half of a file, or more than 200 lines, is refused unless it is meant (a reply cut short looks like that); an anchored edit that removes the lines it names is never stopped by this.
- It never follows a link (a junction or symbolic link) out of the folder, and refuses to link your user folder, a whole drive, Documents, Desktop or Downloads themselves, or Windows and program folders. A project folder inside Documents is fine.
- File contents the agent reads go to RoGenie and the AI model you chose, like the scripts it reads in Studio. Where the folder is on your PC is never sent: RoGenie sees a folder name and paths inside the folder.
- The Bridge runs nothing from your project: no Rojo, no scripts, no Git hooks.
- **Make read-only**, **Pause all file access** or **Unlink** a folder any time in the Bridge window. RoGenie stops using an unlinked folder straight away, and Studio edits to its scripts work again. While access is paused, RoGenie reads those scripts from Studio. Resuming and allowing edits ask you to confirm in Windows.

## Limits

- Windows only, for now.
- A linked folder can hold up to 50,000 files and folders (not counting `.git` and `node_modules`). For a bigger one, link your project's own, narrower folder.
- Up to 16 linked folders per Bridge, 20 files per read and 20 files per change.
- Studio has to be connected for the compile check and for symbol and line-range edits. With Studio closed, RoGenie still reads your files and makes exact text edits, and says they were not compile-checked.
- RoGenie checks the files saved on disk. It does not see unsaved changes in your editor.
- RoGenie's tools that edit, create, rename, move and delete scripts and instances are checked. Inserting a model and running Luau code in Studio are not (Luau that changes Rojo's scripts is reported).
- Git (commit, branch, push) is not part of this yet.

## Project notes in a linked place

[Project notes](https://rogenie.ai/docs/memory#project-notes) live in the place, at `ServerStorage.RoGenie.ProjectNotes`. If your project's Rojo manages `ServerStorage` and deletes what it has no file for, notes saved there would be lost at the next sync. In such a place RoGenie doesn't save notes in Studio. Keep them in `.rogenie/notes.md` in your project instead: RoGenie reads that file into every chat on the place, and with edits allowed it can add to it.

## If something isn't working

See [Rojo projects](https://rogenie.ai/docs/troubleshooting-bridge#rojo-projects) in Bridge troubleshooting.
