Agent

​

What is the Mudstack Agent?

The Mudstack Agent is your creative assistant, available in-app to help you organize, manage, and explore your assets. Whether you have questions about Mudstack, workflows, want to automate tasks, or need help working with your files, the Agent is just a click away.

​

Turning on the Agent for Teams

The Agent is an opt-in feature that needs to be enabled on a per-team basis. To grant access, you must have the necessary permissions:

1. Go to Account Settings → Teams.
2. Select the team you’d like to enable AI features for.
3. Edit the team’s access rules, and add the AI rule.
4. Save your changes.

Only members of teams with the AI rule will have access to the Agent feature.

​

Opening the Agent in Mudstack

Once Agent access is enabled:

• Click the Agent button in the bottom righthand corner of your Mudstack window to open the Agent chat panel.

​

Creating a New Chat

• After clicking the agent button, the Agent chat panel will appear, allowing the user to enter a prompt in the text box located at the bottom of the agent chat panel. After entering your prompt, press ENTER or click the send button in order to send your prompt to the agent.
• To close the agent, click the exit button in the top righthand corner of the agent chat panel.
• To minimize the agent chat panel, click the minimize button located directly to the left of the exit button. This will keep the Agent window panel open, but reduces the amount of screen real estate the agent occupies.
• After minimization of the window, the minimize button will turn into a maximize button. To maximize the agent chat panel after minimizing it, click on the maximize button to expand the agent chat window.
• To open a new agent window panel, click on the + button located to the left of the minimize/maximize button.

​

Prompt Retention

All of your prompts and the subsequent output from the agent will be retained if you exit the agent and then click on the Agent button again to bring up the Agent panel window. However, if you create a new chat and then send a prompt to the agent in this new thread, your old prompts/message history from the old Agent window panel will be erased and cannot be recovered. All of the actions you took with the agent will remain intact, but the history of those actions within the agent panel window itself cannot be seen or reviewed again.

​

What Can the Agent Do?

The Agent uses Mudstack’s MCP tools, Local tools, and Gemini 3 Flash to help with a variety of tasks:

• Search and manage assets to Instantly find, create, edit and add tags to assets, rename assets, push commits, or comment on assets—just ask!
• Work with local data on Agent operations (like renaming, tagging, or commenting) happen locally so you can review and verify changes before pushing them to the cloud.
• Ask about Mudstack and get quick answers about features, processes, best practices, or troubleshooting tips—all from within the app.
• Ask about workflows of external applications and how they coincide with mudstack (e.g. how can I export a Maya file into mudstack and send it to the cloud)
• Ask about how to use external applications related to mudstack (e.g. Unreal, Maya, Unity, Photoshop). The agent has knowledge of best practices outside of mudstack as well with applications that are tangential to mudstack (e.g. what’s the best way to use layers in photoshop? Or what are some best practices for importing files to Unreal?).

​

Sample Actions

Some of the things you can ask the Agent to do:

• “Find all textures in my ‘Environments’ workspace tagged ‘forest’.”
• “Add a ‘v2’ tag to every .fbx file in this folder.”
• “Show the history for asset ‘robot-hero.fbx’.”
• “How do I organize files with libraries?”
• “Explain what version control means in Mudstack.”
• Commit and push all staged files with push summary “Environment assets 02/08/26”)
• Discard changes within the changes page
• Stage files within the changes page
• Unstage files within the changes page
• Rename ‘robot-hero.fbx’ to ‘robot-villain.fbx’
• Purge all old versions of ‘robot-villain.fbx’
• Show a list of the last 20 commits in the workspace
• Add comment “improve texture mapping” to ‘robot-villain.fbx’

See the Available Tools to see what local actions we support with the Agent. See MCP integration for a full list of cloud specific automated actions.

​

Which Model Does the Agent Use?

The Agent is currently powered by Gemini 3 Flash for a high quality conversational and creative experience. In the future, you’ll be able to:

• Configure which LLM you use
• Control MCP tool access and permissions
• Set additional safety and review controls
• Greatly expand upon bulk action capabilities within the Agent
• Embedded AI search within mudstack’s search tool bar for an optimized search experience.
• Cloud tools

​

Have Feedback or Feature Requests?

We’re building the Mudstack Agent for artists and teams like you. If you have suggestions, want new tools, or run into issues, please let us know! Join our Discord to share your feedback, connect with the team, and request features.

​

Available Tools

The agent in the desktop app can make local changes to your content. Here is a list of the tools that are available to the agent:

​

localSearchAssetsTool

Search for assets (both local and committed) by name, type, or folder. Parameters:

• name (string, optional)
• type (string, optional)
• folder (string, optional)

Example Prompt: “Find all .fbx files in /characters.” Currently this will show the results in the agent, not in the search view.

---

​

localRenameAssetTool

Rename an asset locally. Parameters:

• asset_id (string, required)
• new_name (string, required)

Example Prompt: “Rename old_tree.fbx to tree_02.fbx.”

---

​

localCreateCommentTool

Add comments to assets that have been pushed to the cloud. Parameters:

• asset_id (string, required)
• comment (string, required)

Example Prompt: “Add “Needs color correction” comment to mountain.exr.”

---

​

localGetTagsTool

List all tags available in the current workspace. Parameters: none Example Prompt: “Show me all the tags in this workspace.”

---

​

localCreateTagTool

Create a new tag with a specific name and color. Parameters:

• tag_name (string, required)
• tag_color (string, optional)

Example Prompt: “Create a new tag called WIP with a yellow color.”

---

​

localAddTagToAssetTool

Apply an existing tag to a specific asset. Parameters:

• asset_id (string, required)
• tag_id (string, required)

Example Prompt: “Tag castle.obj robot.”

---

​

localUpdateTagTool

Change the name or color of an existing tag. Parameters:

• tag_id (string, required)
• tag_name (string, optional)
• tag_color (string, optional)

Example Prompt: “Rename the Draft tag to In Progress and make it blue.”

---

​

searchLocalChangesTool

Find all local uncommitted changes (staged or unstaged). Parameters: none Example Prompt: “List all files with local edits.”

---

​

localStageChangesTool

Stage specific local changes to prepare them for a commit. Parameters:

• file_list (array of strings, required)

Example Prompt: “Stage waterfall.jpg and grass.png for commit.”

---

​

localUnstageChangesTool

Move staged changes back to the unstaged area. Parameters:

• file_list (array of strings, required)

Example Prompt: “Unstage tree_1.fbx from the commit list.”

---

​

localDiscardChangesTool

Permanently delete local changes (destructive). Parameters:

• file_list (array of strings, required)

Example Prompt: “Revert all edits to obelisk.obj.”

---

​

localCommitAndPushChangesTool

Commit your staged changes and push them to the Mudstack cloud. Parameters:

• commit_message (string, required)

Example Prompt: “Commit with message “Added new lighting setup” and push.”

---

​

localAssetHistoryTool

View the full version history of a specific asset. Parameters:

• asset_id (string, required)
• num_versions (integer, optional)

Example Prompt: “Show all prior versions of spaceship.glb.”

---

​

localSearchCommitsTool

Search through the history of commits in the workspace. Parameters:

• query (string, optional)
• num_commits (number, optional)

Example Prompt: “Show me the details of the commit ‘Added new lighting setup’”, Find the last 10 commits containing “logo update”.

---

​

localGetCommitDetailsTool

View the metadata and file list for a specific commit. Parameters:

• commit_id (string, required)

---

​

localPurgeVersionTool

Delete a specific version of an asset. Parameters:

• asset_id (string, required)
• version_id (string, required)

Example Prompt: “Remove experimental version from clouds_v2.png.”

---

​

localPurgeOldVersionsTool

Delete all previous versions of an asset, keeping only the latest. Parameters:

• asset_id (string, required)

Example Prompt: “Cleanup and only retain most recent version of propeller.fbx.” See MCP integration for a full list of available Cloud specific tools.

​

Best Practices

• Explicit prompts are better than implicit prompts.
  • Example: If I have 5 changes that already exist, and I want to make new changes and only push the new changes, I should explicitly state to only “push the changes that I just made”
• Selecting files before submitting a prompt will add the selected files to the context of the prompt.
  • Example: After selecting files, ask the agent to “Add the tag robot to the selected files”.
• You can ask the agent to perform multiple actions within a single prompt. The agent will then sequentially run through each action (e.g. add tag “Hero model” to the selected files, stage and push selected files with push summary “Hero model push 02/07/26”).
• Limit the number of files and you are interacting with the agent to 50 at a time. Currently, the agent can handle more than that number, but will do so in a bulk fashion that can create some errors. We’ve noticed that there have been some errors when making changes to more than 50 files at once.
• Limit the number of tags you are creating/updating to 300 at a time. Creating more than 50 tags at once will do so in batches (usually 50 at a time, or sometimes 25 at a time). The agent will ask you if you want to keep going when it is performing operations in batches like this. Simply saying “yes” will continue the operation.
• When committing/pushing files, include a push summary within the prompt. The agent can still push/commit your files without a push summary, but it will usually ask for one before it does so or it will name the push summary itself with a generic name e.g. “pushed selected staged changes”. A push summary will expedite the process and ensure the push has a name that is unique to what you’re pushing.
• When committing/pushing files, either select the files or explicitly state which files you want to commit or push within the agent panel window. Not doing so can cause the agent to occasionally push other files within the unstaged changes area that you may not want to push yet.
• You can ask the agent for the tools it has access to. A great way to look ask for this is to ask “Display your local tool capabilities”

​

Current Caveats with the Agent

The agent is still in beta and there are some caveats to be aware of:

• The agent’s context window is 1,000,000 tokens. If you do exceed context limits, you can create a new thread to resolve the issue.
• Creating a new thread will start a new conversation and you will lose the previous one.
• The local tools are currently focused on files and changes. We are still adding more tools to support additional actions.
  • Folder renames & moves aren’t supported currently.
  • Library creation and editing isn’t supported currently.
  • Bulk actions for POSTs do not exist currently, so you may see a large amount of singular POSTs when making bulk changes. Generally any bulk changes over 50 can be spotty currently until we update the tool to support larger actions.
  • Cannot lock or unlock files with the agent
  • Cannot move files
• The agent is not available in the web client
• The agent and its ability to assist you is unique to the workspace you are in. You cannot perform actions across multiple workspaces you have access to with the agent.
• When committing changes with the agent, you may see some staged changes you wanted to be pushed stay in the staged area. Asking why this happened to the agent will usually prompt the agent to apologize and ask if you’d like to push the files that were not pushed which it will do promptly upon you confirming that you do want to push those files.
• Restoring and trashing files is not available currently. The agent will tell you how to perform the action, but it cannot do so itself.
• Some tools may show as in progress, even though the action is complete. This may occur when multiple tool calls are used in sequence (e.g. creating 100 tags with a single prompt).
• Pushing large quantities of items (be it files or tags with the agent, not the mudstack app itself) at once can be spotty at times. We have pushed up to 300 files/tags at a time with the agent successfully before without issue, but we have run into instances where we have encountered errors pushing large quantities of files/tags before. We have found that selecting the files and/or tags or explicitly calling out the files and/or tags in the prompt improves the committing/pushing results exponentially. Saying “commit all staged changes” opens up the opportunity for more errors to occur.
• Pushing more than 50 tags/files at once will takes a little longer than pushing say 10-15 files.