> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant/quick-start.md).
# AI coding assistant quick start
Convai extends Unity's MCP server with SDK-aware tools so a coding agent such as Codex, Claude Code, or Cursor can configure Convai components directly in your project. Use this quick start the first time you connect an agent to a project that already has the Convai Unity SDK installed. At the end, your agent has managed instructions installed and the AI Coding section reports every Convai tool as registered.
### Prerequisites
* space.vars.unity\_recommended\_version or later — Convai's AI coding tools require Unity 6000 or newer.
* The Convai Unity SDK installed in the project. See [Install the Convai Unity SDK](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/installation.md).
* A compatible Unity AI Assistant package (`com.unity.ai.assistant`, version `2.13.0` or later and below `3.0.0` — a `2.13.0` build must carry prerelease tag `pre.2` or later, and a `3.0.0` build is accepted only as a prerelease, never the final release). Install it manually, or install it from inside this walkthrough.
* A supported coding agent installed on your machine, such as Codex CLI, Claude Code, or Cursor. See [Supported coding agents](/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) for the full list.
### Open AI Coding Setup
{% stepper %}
{% step %}
#### Open the AI Coding section
In the Unity Editor menu bar, select **Convai > AI Coding Setup**. This opens the **AI Coding** section of the Convai Editor window.
The section's **Setup Health** card reports four readiness rows: **Unity 6000+**, **Unity AI Assistant**, **Packaged Convai Skill**, and **Convai MCP Tools**. Each row reads **Ready** or **Needs attention**.
{% endstep %}
{% step %}
#### Accept the Unity MCP terms
Unity may prompt you to accept the Unity AI Assistant and MCP server terms of service the first time the feature activates in this project. Accept the prompt so Unity's MCP server and Convai's tools can register. If no prompt appears, open **Project Settings > AI > Unity MCP Server** directly to accept the terms and confirm which MCP clients are connected to your project.
{% endstep %}
{% step %}
#### Resolve any row that shows a warning
Each unready row shows a **Fix** button. Click **Fix** next to **Unity AI Assistant** to install `com.unity.ai.assistant@2.14.0-pre.1` through Package Manager — Unity recompiles and the row updates automatically. Click **Fix** next to **Packaged Convai Skill** or **Convai MCP Tools** to refresh package assets and re-register Convai's tools without reinstalling the Assistant package.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Clicking **Fix** while Unity is compiling, updating packages, or in Play Mode shows a warning and does not start the repair — exit Play Mode first, since repair never exits Play Mode for you. A **Fix** button is only disabled outright while a repair it started is already running.
{% endhint %}
### Install your coding agent's managed instructions
{% stepper %}
{% step %}
#### Choose your coding agent
Scroll to the **Managed Project Instructions** card. Convai lists each supported agent with the file it manages — for example `AGENTS.md` for Codex, `CLAUDE.md` for Claude Code, and `.cursor/rules/convai-unity-sdk.mdc` for Cursor. See [Supported coding agents](/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) for the complete list and per-agent notes.
{% endstep %}
{% step %}
#### Install the managed instructions
Click **Install** next to your agent. Convai writes a sentinel-delimited block, marked by `` and ``, into that agent's file without disturbing any existing content. The button changes to **Update** once the block exists, and **Remove** becomes available to delete it later.
{% endstep %}
{% endstepper %}
The managed instructions direct your agent to read `Packages/com.convai.convai-sdk-for-unity/AIAssistantSkills/convai-unity-sdk/SKILL.md` and its linked references, use Unity's generic MCP tools for GameObjects, scripts, and scenes, and use Convai's tools for SDK configuration and diagnosis.
### Verify the tool count
The **Convai MCP Tools** row reads `20/20 registered` once Unity's MCP registry has registered all twenty Convai tools under tool contract version 4. If the count is lower or the row lists a missing or unexpected tool name, click **Fix** next to **Convai MCP Tools** to refresh the registry and recompile.
{% hint style="success" %}
Setup is complete when all four rows read **Ready** and **Convai MCP Tools** reads `20/20 registered`.
{% endhint %}
### Prompt the agent to build your scene
With managed instructions installed and the tool count verified, prompt your agent in plain language. Convai's tools handle SDK-specific configuration; your agent's Unity MCP tools handle generic GameObjects, scripts, and scene operations.
| Task | Example prompt |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| Build a scene | "Set up a training-simulation room with a Convai Player and a Convai Character named Instructor." |
| Add the chat UI | "Add the shipped chat UI to the scene so the transcript is visible during the conversation." |
| Switch push-to-talk or hands-free | "Switch the room to Push to Talk input mode." |
| Add objects | "Add a red fire extinguisher GameObject next to the workbench." |
| Enable vision | "Turn on vision for the Instructor character so it can see the workbench." |
Vision setup is not one of Convai's twenty foundation tools, so your agent configures it by editing `ConvaiRoomManager` and adding `ConvaiVisionPublisher` directly. See [Vision quick start](/api-docs/plugins-and-integrations/convai-unity-sdk/features/vision/quick-start.md) for the exact fields it sets.
### What to try next
Prompt your agent for two or three of the tasks above in your own project, and check the resulting scene in the Hierarchy before entering Play Mode.
{% content-ref url="/pages/oXL608mEMdrEEudHoaSJ" %}
[AI coding assistant](/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant.md)
{% endcontent-ref %}
{% content-ref url="/pages/4fzoj3RtQTbbG69I9A9p" %}
[Supported coding agents](/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md)
{% endcontent-ref %}
{% content-ref url="/pages/Gd4pCWmZTgamoBbmr0R2" %}
[MCP tools reference](/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant/mcp-tools-reference.md)
{% endcontent-ref %}
{% content-ref url="/pages/6KguvwDVvWMYC4R123tO" %}
[Troubleshoot AI coding assistant setup](/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant/troubleshooting.md)
{% endcontent-ref %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/ai-coding-assistant/quick-start.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.