The Assistant 

The Assistant is an AI agent built into Ornatrix App. You describe what you want in plain language and it builds it: it adds operators, tunes their parameters, renders the viewport to check its own work, and adjusts until the result matches what you asked for. It works on your live groom, so everything it does appears in the Operator Stack exactly as if you had done it by hand, and everything is undoable.

The Assistant is experimental. It requires your own Anthropic API key: Ornatrix does not include or resell access to the model, and usage is billed to your own Anthropic account.

 

Requirements 

• The AI Assistant component of Ornatrix App, offered by the installer when it asks which components to install. It is selected by default and adds about 300 MB. Part of it is downloaded while the installer runs, so the machine needs an internet connection at that point.
• An Anthropic API key, from https://platform.claude.com. The key is yours; you are billed for what the Assistant uses.
• An internet connection while you use it. The Assistant sends your requests to Anthropic's servers to be processed.

 

Entering your API key 

There is nothing to switch on: the Assistant's controls are always there. It cannot run anything until it has your key, which you enter once and Ornatrix remembers.

1. Open the Console panel and tick Assistant in its toolbar.
2. A password field appears next to the checkbox. Paste your Anthropic API key there. The key is stored in your local settings and is sent only to Anthropic.

The command line at the bottom of the Console now accepts plain language instead of Python. The hint text changes to confirm this.

Should you make a request before entering a key - from the Console, or from the Auto button described below - the Assistant opens the Console for you, ticks Assistant and puts the cursor in the key field, so the answer is where you are already looking. If the AI Assistant component was never installed, a dialog says so instead, and tells you which part of it is missing.

 

Using it 

Type what you want and press Enter. Some examples that work well:

• "Create a furry sphere."
• "Make the hair longer and curlier."
• "This looks too uniform - add some variation to the length."
• "Show me a render."

Two things are worth knowing to get good results:

• It works on the current groom. If you want it to start fresh, clear the scene first, or say so in your request.
• It can see its own renders. Asking it to "check" or "show" the result makes it render and look at the image, which noticeably improves what it produces on visual requests such as curliness or density.

Everything the Assistant does goes through the normal command stack, so it is all undoable. By default a whole request is folded into a single undo step named after what you asked for, so Ctrl+Z takes the groom back to how it was before the request and Ctrl+Y brings all of it back. Anything you changed yourself while the Assistant was working is part of that same step. See Undoing a request below.

 

Authoring a groom's parameters 

A groom can present a small panel of parameters of its own - a handful of named controls such as Length, Curliness or Random Seed - which stand in front of the operator stack, so the groom can be used, and handed to someone else, without their having to know which operator each value belongs to. These appear in the Groom Properties panel, and in the properties of a Groom operator which references the groom. Which parameters a groom has is decided by whoever built it, and writing them out by hand is the fiddly part: each one has to name the operator parameter it drives, along with a range and a default.

The Assistant can do that work for you. The Groom Properties panel carries an Auto button beside Edit, which opens a short menu.

 

Detail levels 

The top of the menu offers five levels of detail:

1. Minimal
2. Basic
3. Standard
4. Detailed
5. Exhaustive

Picking one asks the Assistant to go through the groom's operators and build the panel at roughly that size. A Minimal panel exposes only the few values that matter most; an Exhaustive one covers everything that noticeably changes the look of the character, grouped into categories. In between, the number of parameters is chosen to stay readable in the panel rather than to be complete. The Assistant tries out the parameters it picks in order to settle on a sensible range for each, so this is a real piece of work rather than an instant one; the badge at the top of the window reports what it is doing, as with any other request.

Existing parameters are not thrown away. If the groom already has some, the Assistant checks them, corrects anything broken, and builds the new ones on top - so you can ask for Minimal, adjust the result by hand, and later ask for Exhaustive to expand on what you kept.

 

Refining what is there 

The last entry, Refine..., is for a single change to a panel you are otherwise happy with. It opens a dialog where you describe what you want in your own words, for example:

Add the gradient map's middle parameter as a "Color Blend" param

Only what you describe is changed. Every other parameter keeps its name, type, expression, range, default, group and position: the Assistant is told not to rename, regroup, reorder or re-range anything to tidy the panel up, and not to add parameters you did not ask for. If it notices a problem elsewhere while it works, it mentions it in its reply and leaves it alone for you to decide about. When it is done it says in a sentence or two what it changed, so you can see the edit stayed within what you asked.

Ctrl+Enter submits your description. Enter starts a new line, so a longer request can be laid out over several. The next time you open the dialog your previous request is offered again, selected, since a follow-up is usually a variation on the one before; typing replaces it outright when it is not.

If the groom has no parameters yet, Refine... creates them from your description alone, covering what you asked for and nothing beyond it. That is the way to get one specific small panel without going through a detail level first.

Either kind of request goes to the same Assistant as the Console does, so the work appears in the Console, the badge and border behave as described below, and the whole request is one undo step. If the Assistant is already busy, your request is queued behind the current one.

 

While it is working 

A request is rarely instant. A single one usually becomes several operations: the Assistant looks at the current scene, makes a change, renders the viewport to see the result, and then refines. While that is happening the application makes it plain that an agent is in control.

• The window is framed. A coloured border runs around the whole application and pulses about once a second for as long as the Assistant is working. It stops pulsing and holds steady when the Assistant is waiting for an answer from you, so a glance at the edge of the screen tells you whose turn it is.
• A badge appears at the top of the window, naming what the Assistant is doing right now - "Adding an operator", "Rendering the groom" - and how long the request has been running.
• The Console records each operation, so you can follow the work in detail while it happens and read it back afterwards. Long replies are shortened to their first line; hover it to read the whole reply, and copying the line copies the full text.

 

Cancelling 

The badge carries a Cancel button, and a second one appears at the end of the Console command line while a request is running. Either one abandons the request.

The Assistant stops a moment later rather than instantly, so a cancelled request has usually changed something already. Ornatrix asks what to do with those changes: a dialog names the step and offers Keep Changes, which leaves them in place as one undo step you can still undo by hand, or Undo Changes, which takes the groom straight back to how it was before the request. Undoing this way is not destructive - the whole request stays on the redo stack, so Ctrl+Y brings it back if you change your mind.

Tick Don't ask again in that dialog to always do whatever you chose, without being asked in future. The choice can be changed later from the settings described below.

 

Typing while it works 

You do not have to wait for a request to finish before typing the next one. A message sent while the Assistant is busy is queued rather than lost, and goes out as soon as the current request ends; the badge shows how many messages are waiting. Cancelling discards the queue along with the request.

 

Undoing a request 

A single request usually becomes many operations, and undoing them one at a time would be tedious and easy to get wrong. Ornatrix therefore records the whole of a request as one undo step, named after what you asked for, so the Edit menu reads for example "Undo: AI: make the hair curly". One Ctrl+Z returns the groom to the state it was in before you pressed Enter, and one Ctrl+Y reapplies the entire request.

The step covers everything that happened while the Assistant was working, including changes you made alongside it. That is deliberate: while a request runs you are free to keep working, and undoing partway into a shared stretch of history would leave the groom in a state neither of you produced.

If a request is followed by further messages you typed while it was running, all of them belong to the same step, and its name says so.

Occasionally a request cannot honestly be described as one step, and Ornatrix then leaves its operations as separate undo entries rather than promising something it cannot deliver. That happens when the Assistant replaces the whole groom more than once during a request (each replacement discards the previous one, which no later undo can bring back), and when it undoes further back than the point its own request started from.

Two settings under Interface -> Assistant control this:

• Group AI Assistant changes into a single undo step - on by default. Turn it off to have every operation stay its own undo entry, as any other edit would.
• When an AI Assistant action is cancelled - what happens to the changes of a cancelled request: Ask what to do (the default, described under Cancelling above), Keep the changes, or Undo the changes.

 

Notes and questions 

The Assistant can also put messages on screen instead of only in the Console. They appear as cards in the bottom-right corner, labelled Assistant.

• Passing notes fade away on their own after a few seconds. They report something the Assistant has just done and that you can safely miss.
• Pinned notes stay until you close them. The Assistant uses these for something worth reading after the fact: what it changed and why, a caveat, or a result you need to act on.
• Questions offer a row of answers to choose from, and the Assistant waits for your choice before carrying on. Use them: a question means the request was genuinely ambiguous, and answering it gets you what you meant rather than a guess. If you close a question instead of answering it, the Assistant is told that you declined, picks the most reasonable option itself, and tells you which one it took.

Each of these is written to the Console as well, so the conversation stays complete once a card is gone.

 

What it can and cannot do 

The Assistant can only operate on grooms. It can inspect the scene and the operator graph, create operators and connect them, read and change operator parameters, read and rewrite the groom's own parameters panel, load and save grooms, resolve asset search paths, render the viewport, and manage operator plugins.

Beyond that it has no shell access and no way to browse the web: it cannot run commands, and it reaches nothing but your groom and Anthropic. It can read files, which is what lets it follow a skill you have added in the folder the button beside the API key field opens, but it cannot write them unless you turn on Let the Assistant write files under Interface -> Assistant. That switch is off by default and exists mainly so the Assistant can record a skill of its own; with it on, it can write anywhere that folder reaches. It also cannot close the application.

 

Cost and privacy 

The Assistant sends your typed requests, a description of your groom's structure (operator names, types and parameter values), and any viewport renders it takes, to Anthropic for processing. It does not send your groom files or your source meshes.

Because you supply your own API key, all usage is billed directly to your Anthropic account. A single request that involves several renders costs more than a simple question. If cost matters to you, prefer specific requests over open-ended ones, and cancel a request that has clearly gone the wrong way rather than letting it finish.

 

Troubleshooting 

It says the AI Assistant is not installed. The AI Assistant component was not selected when Ornatrix App was installed, or the part of it which is downloaded during installation never arrived - most often because the machine was offline at the time, or a proxy or firewall blocked the download. The dialog says which of the two it is. Run the installer again with AI Assistant ticked to add it.

"ANTHROPIC_API_KEY is not set". No key has been entered in the field next to the Assistant checkbox.

It reports that the application is unreachable. The Assistant reaches your groom through the same local control endpoint described in Using Ornatrix with Claude, which starts along with the application. This normally means the endpoint could not start - most often because its port is already in use by another running copy of Ornatrix App.

It seems to be taking a long time. The badge at the top of the window says what it is doing and for how long. A request that involves several renders legitimately takes a while. If it is not going anywhere, press Cancel.

Nothing happens when I type. Check the badge: if a request is already running, your message has been queued and will be sent when that request finishes. If the border is steady rather than pulsing, the Assistant is waiting for you to answer a question card in the bottom-right corner.

It stops responding partway through a request. Operations that change the scene have to wait for the application to draw a frame. If the application is busy with a very heavy groom, an operation can time out and the request will stop. Simplify the groom or reduce the hair count and try again.

For anything else, the Assistant writes a diagnostic log named assistant_sidecar.log next to the Ornatrix App executable, recording every operation it attempted and any error. Include it when reporting a problem.

 

Related 

• Using Ornatrix with Claude - drive Ornatrix from Claude Desktop or other AI tools instead of the built-in panel.
• Scripting with the Python Console - the same panel, in scripting mode.
• The Operator Stack - where the Assistant's work appears.

Missing Something? Let us know if this page needs more information about the topic.