You describe a course; Claude builds it, and proves it against your Unity project. This page is the whole of that, step by step, in the words you say to Claude and what you will see back. It assumes you have finished setting up: the connector is running, Unity is open on a project, and your Claude has the Mosaic tools.
There are three places, and knowing which is which explains almost everything you will see.
On your machine. Claude drives it through the connector: creates objects, takes screenshots, records GIFs. Captures are filed inside the project, under a folder named after the course.
On the Mosaic service, in your workspace. One folder per course, with one file that is the source of truth for everything: course-config.json. Every document is rendered from it, so you change the config, never the documents.
The only thing you talk to. It has sixteen Mosaic tools; you will see their names in its replies (course_define, course_gates and so on), which is how you know where you are. You never call them yourself.
The path is always the same: describe the course, agree what it teaches, build it, gate it, photograph the steps in Unity, copy the photographs in, gate again, and download. A course is finished when the gates say GO.
You have a Unity project you teach from, or want to. Mosaic is already added to it (the install page, step 2). Start here.
Open the project in Unity, make sure the connector window is running, then:
Say what it is, who it is for, how long, how many people, and what a learner can do at the end. Name the project. That is all Claude needs to create it.
Claude will propose objectives, a plan for each day, a lab and a knowledge check, and ask you about the things only you know. Answer in your own words; it writes the configuration and validates it as it goes.
No project, no course. Twenty minutes to the same place Path A starts from.
In Unity Hub: New project, 3D (URP), any name, any location. Do not open it yet.
In a terminal (PowerShell on Windows), from the folder where the connector lives:
mosaic-connector add "C:\Users\me\Projects\MyNewCourse"The first open fetches the three Mosaic packages from the registry and compiles them: a few minutes. Package Manager will show Signature: Missing and Pre-release on them; both are normal. When the Console settles, the connector window says connector ready.
add once per project. Captures are filed inside each project under a folder named after the course, so two courses on one project never overwrite each other.Both paths arrive here with a VALID configuration. From here to GO is one loop.
With Unity open on the project the course is taught from:
For every step, set the Editor up as the step describes and ask for the capture, naming the step. Claude captures the whole Editor by default and files the image under the course inside the project.
\lighting-in-a-day\screenshots\week-1\…) and captureDetail: composited 9 of 9 panels into 1918x934 — the whole Editor, as you see it. For a still of one panel say capture the Inspector; for motion say record a Play-Mode GIF of this step.They are in your project; the course is on the service. This carries them across, renames the folders to the course's own unit word (days, not weeks), and removes from the course anything you have since deleted in the project.
Eleven checks, in the order they run. The verdict is GO only when none of them is NO-GO. SKIP means the gate could not check, which is not a failure.
| Gate | What it asks |
|---|---|
| Config valid | Is the configuration complete and well-formed? Every error names the field and what belongs in it. |
| Cross-layer consistent | Do the config, the build record and the captures agree with each other about ids, scenes and objects? |
| Quality (pro bar) | Is every document present and not a stub? Is every objective taught somewhere and assessed somewhere? |
| Naming (unit word) | If the course teaches in days, is nothing filed under "week"? |
| Completeness | No placeholders left in any rendered document. |
| Alignment | Do the lab, the slides and the live-coding script all render the same steps? |
| Capture coverage | Does every planned step have a photograph linked to it? Needs 100%. |
| Media quality | Are the images real: not blank panels, not byte-identical duplicates, GIFs that actually move? |
| Packages | Does the recorded project have the packages the course claims to teach? |
| Claims vs the project | Does the Unity version the course states match the project that was recorded? |
| Durations (report) | Does the content fit the day? Reports only; never blocks. |
Below the gates, a Deliverables block lists what exists: the PDF, the site, how many usable screenshots, and whether there is a Play-Mode GIF. The GIF is optional polish, but it is the one thing that shows the game running.
| To… | Do this |
|---|---|
| Start a session | Open the project in Unity; make sure the connector window is running (mosaic-connector run). It reconnects on its own if Unity restarts. |
| See your courses | list my courses |
| Delete a course | delete the course called X — Claude asks you to confirm; it cannot be undone. |
| Remove a bad photograph | Delete the file inside the project's course folder, then import the captures again: the import mirrors the project, so it leaves the course too. |
| Upgrade Mosaic | Close Unity, wait for it to fully exit, run mosaic-connector add <project> again. It says what moved. Reopen Unity. On Windows, if Unity reports EPERM … rename while importing, click Retry; excluding the project's Library folder from Defender's real-time scan stops it recurring. |
| Check your connector build | mosaic-connector version |
| Editor refused: "signed in as … but this code is issued to …" | Your code is tied to your Unity ID. Sign in to Unity as that account (Unity Hub, or the account menu in the Editor). Until then the course tools all work; only photographing is refused. |
| A Pro tool answers "Mosaic Pro has no licence on this machine" | The Pro tools (photographing, measuring) carry a licence the connector fetches from the service on every connection and writes beside its config. Start the connector (mosaic-connector run) and try again. Mosaic › Pro Licence in Unity shows what it holds: who it is issued to, which features, and until when. It renews itself while your access code is valid; when the code is withdrawn it stops within a week. |
| The connector says your access code has expired | Nothing to do on your machine. Leave the connector window open: it checks every ten minutes and connects on its own once the code is extended. Tell whoever issued the code. |
| Use a second machine | Set it up with the same code: your access code works on up to two of your own machines, and only one Unity Editor can be connected at a time. A third machine is refused and says which two hold the code. Codes are personal; a colleague needs their own. |
| Drive the Editor directly | Anything the Editor can do: create a cube called Hello, enter play mode, show me the console errors. Ask what can the Editor do with materials? to see the routes. |
Plain sentences work. These are the ones that map most directly onto what happens.
create a course from this project: …
the day is split into two sessions
rephrase objective two as …
make the pass mark 80%
build the course
record the Unity project into the course
run the gates
give me the links / link me the syllabus
seed the capture plan
capture step day1-s02-01 for this course
capture the Inspector / the Scene view
record a Play-Mode GIF of this step
import the captures / attach the captures
is my Unity Editor connected?
why did the media gate fail?
which steps still have no capture?
what did you assume about this course?
Three of the longer jobs are available as slash commands in Claude Code. They are not
files on your machine: they come from the service, so they are always the current
version, and they start a guided conversation rather than running something blindly.
Type /mcp__ and the list appears.
| Command | What it starts |
|---|---|
/mcp__mosaic__define_course | Interviews you about audience, level, days and hours, what learners build, and which Unity features are in scope, then writes and validates the configuration. Nothing is assumed silently. |
/mcp__mosaic__build_day | Performs one day's steps in your connected Editor and photographs each one as it goes. |
/mcp__mosaic__update_course | Applies a change and then proves nothing else broke, by regenerating and re-running the gates. |
Everything these do can also be asked for in your own words. The commands exist so the long jobs start the same way every time.
You never call these; Claude does. Their names appear in its replies, and this is what each one is.
| Tool | Does |
|---|---|
| workspace_list | Lists your courses. |
| course_define | Creates a course from your paragraph, and reads back what it assumed. |
| course_write_config | Saves the configuration and validates it; at VALID, reads back the teaching decisions. |
| config_validate | Validates without saving. |
| course_regen | Renders every document from the configuration. |
| course_record_build | Records what the connected Unity project actually contains. |
| course_gates | The fourteen checks and the verdict. |
| course_import_captures | Copies the project's photographs into the course; mirrors deletions. |
| course_sweep | Checks a course for broken links, local paths and bad JSON. |
| course_delete | Deletes a course, after you confirm. |
| render | Runs one renderer on its own, including seed_capture_plan and attach_captures. |
| derive_workshop | Makes a short workshop and a webinar edition from a course. |
| artifact_link | Download links for everything the course produced. |
| editor_status | Is the Editor answering, since when, with how many tools. |
| editor_routes | What the Editor can do; with a route name, that route's parameters and allowed values. |
| editor_call | Does one thing in the Editor. With a course named, files anything it writes under that course. |
<project>\<course-id>\screenshots\ and copied to the course by import the captures. Nothing from the Mosaic pipeline itself is ever placed on your machine.