Can Atlas modify Unity .meta files or scene YAML in CI?

Atlas never touches .meta files or scene YAML without showing you first. In a headless CI environment, this means Atlas will not modify these critical Unity asset files unless explicitly configured and reviewed, ensuring project integrity.

How does Atlas handle Unity Package Manager (UPM) dependencies in CI?

Atlas can read your `Packages/manifest.json` and the packages resolved by the Unity Package Manager (UPM). This allows it to understand your project's dependencies when analyzing or modifying C# scripts, ensuring context-aware changes.

What Atlas tools are essential for Unity CI automation?

For Unity CI automation, essential Atlas tools to pre-approve include `read` for code analysis, `edit` for C# file modifications, and `bash` for executing external commands like `dotnet format` or Unity Test Framework (NUnit) via the command line.

How can I ensure Atlas's changes don't break Unity gameplay logic?

Atlas drafts a plan in a read-only plan agent before execution. In CI, you should always follow Atlas's changes with automated Unity Test Framework (NUnit) tests (EditMode and PlayMode) to validate that gameplay logic and MonoBehaviour lifecycle order remain correct.

Can Atlas help optimize MonoBehaviour performance in CI?

Yes, Atlas can be prompted to hoist GetComponent calls out of Update and cache them in Awake, reducing per-frame allocations. This optimization can be automated in CI, with Atlas applying the change to your MonoBehaviour scripts.

How do I specify the AI model for Atlas in a Unity CI pipeline?

You must explicitly set the model using the `--model provider/model` form, for example, `--model github/copilot-gpt-4`. This ensures Atlas uses the correct AI model for your Unity C# code analysis and generation tasks in CI.

What if an Atlas headless run needs user input for a tool?

If an Atlas headless run encounters a tool call that requires user input (an `ask` permission rule), the session will halt. For CI, all necessary tools must be pre-approved with `allow` rules in Atlas's permission configuration to ensure non-interactive execution.

Run Atlas Headless in CI for Unity Projects in 2026

In 2026, Unity developers can run Atlas headless in CI pipelines to automate code modifications, ensuring consistent quality and rapid iteration on C# gameplay code. This non-interactive mode allows Atlas to refactor MonoBehaviour scripts, add Unity Test Framework (NUnit) tests, and apply dotnet format without manual intervention, providing machine-readable output for subsequent pipeline steps.

How to run Atlas non-interactively in Unity CI pipelines?

Running Atlas non-interactively in a Unity CI pipeline in 2026 is straightforward using the atlas run command. This command's default mode sends a single prompt, streams events to stdout, and exits when the session goes idle, making it ideal for automated workflows.

To integrate Atlas into a Unity CI pipeline, you invoke `atlas run` with your desired prompt as an argument. For instance, to refactor a MonoBehaviour script, you might provide a prompt like "Hoist a GetComponent call out of Update and cache it in Awake in MyPlayerController.cs". Atlas will then execute its plan, using tools like `read` and `edit` to modify your C# files within the Unity project structure, specifically targeting files under the `Assets/` folder. The `atlas run` command is designed for this headless operation, ensuring that your CI environment can leverage Atlas's capabilities without requiring a terminal interface. The output can be streamed as raw events using `--format json`, which is crucial for subsequent pipeline steps that need to parse Atlas's actions and results programmatically.

How to get machine-readable output from Atlas in Unity CI?

To obtain machine-readable output from Atlas in a Unity CI pipeline, pass the `--format json` flag to the `atlas run` command. This ensures that Atlas streams raw event data to stdout, allowing other pipeline steps to parse and react to its actions, such as code edits or test results, in 2026.

When running Atlas in a CI environment for Unity projects, it is often necessary for subsequent pipeline steps to programmatically understand what Atlas has done. By adding `--format json` to your `atlas run` command, Atlas will output a stream of JSON events rather than human-readable prose. This event stream details every action Atlas takes, including tool calls (e.g., `bash`, `read`, `edit`, `todowrite`), plan drafts, and file modifications. For a Unity project, this means a CI job could parse the JSON to confirm that a GetComponent call was indeed hoisted, or that new Unity Test Framework (NUnit) tests were added under `Tests/`. This structured output is essential for building robust, automated workflows that can validate Atlas's work or trigger further actions like running `dotnet format` on modified files.

How does Atlas ensure safety and review in headless Unity operations?

Atlas ensures safety and review in headless Unity operations through permission-gated tool calls and unified diffs, even without a human present in 2026. Every Atlas tool call is permission-gated against allow, ask, and deny rules, and it computes a unified diff for every file edit.

In a headless CI environment, Atlas's safety mechanisms are paramount. Before any tool, such as `edit` or `bash`, is executed, Atlas checks against pre-configured permission rules (allow, ask, deny). For headless runs, all necessary tools must be explicitly `allow`-listed in the permission configuration, as there is no interactive prompt to answer an `ask` rule. Atlas also drafts a plan in a read-only plan agent before switching to a build agent, providing an internal review step. Crucially, for every file edit, Atlas computes a unified diff and surfaces it. While a human cannot approve it interactively in CI, this diff can be captured from the `--format json` output and reviewed post-run, or used by a subsequent pipeline step to validate changes. Atlas also snapshots file changes as git patches, allowing edits to be diffed and rolled back if necessary, providing a robust safety net for modifications to MonoBehaviour scripts or ScriptableObjects within your Unity project. Atlas never touches .meta files or scene YAML without showing you first, ensuring critical Unity asset integrity.

How to configure Atlas permissions for Unity CI tools?

To run Atlas headless in a Unity CI pipeline, you must pre-approve the tools it needs through its permission configuration, as there is no interactive prompt to answer an ask rule. This ensures that tools like edit and bash can operate on your C# files and Packages/manifest.json without interruption in 2026.

Atlas's permission system is a core safety feature. For headless CI runs, any tool Atlas might use to interact with your Unity project, such as `bash` for running `dotnet format` or `edit` for modifying C# scripts, must be explicitly pre-approved. This is done by configuring `allow` rules in Atlas's permission settings. Without pre-approval, any tool call that defaults to `ask` would halt the headless session, as there's no user to provide consent. For Unity development, common tools to allow include `read` for inspecting MonoBehaviour scripts and `Packages/manifest.json`, `edit` for modifying C# source files, and `bash` for executing commands like `dotnet format` or invoking Unity Test Framework (NUnit) via the command line. This explicit configuration ensures that Atlas operates within defined boundaries, preventing unintended actions in your automated Unity build environment.

How to resume or fork an Atlas session in Unity CI?

You can resume or fork a prior Atlas session in a Unity CI pipeline using `--continue`, `--session`, or `--fork` flags, allowing a job to build on an earlier run or re-attempt a failed step. This is particularly useful for complex Unity refactoring tasks that might span multiple CI stages in 2026.

For more complex or multi-stage CI workflows in Unity, Atlas provides options to manage session state. If a pipeline step fails or needs to be re-run, you can use `--continue` or `--session <session_id>` to pick up exactly where a previous Atlas run left off. This is invaluable when Atlas is performing a significant refactoring across multiple MonoBehaviour scripts or adding a suite of Unity Test Framework (NUnit) tests, and the CI job needs to be restarted. The `--fork <session_id>` option allows you to create a new session based on the state of an existing one, enabling parallel experimentation or alternative approaches from a common starting point. These capabilities ensure that your Unity CI pipelines can be resilient and efficient, avoiding redundant work and allowing for granular control over Atlas's execution flow, especially when dealing with large codebases or intricate changes to `Assets/` and `Packages/manifest.json`.

Step by step

01Prepare Unity Project: Ensure your Unity project has an `Assets/` folder and a `Packages/manifest.json` file, and that Atlas can access these for code indexing.
02Configure Atlas Permissions: Pre-approve necessary Atlas tools (`read`, `edit`, `bash`, `todowrite`) in Atlas's permission configuration to allow headless operation on Unity C# files and project settings.
03Invoke Atlas Headless: Run `atlas run --format json --model github/copilot-gpt-4 --command "Hoist a GetComponent call out of Update and cache it in Awake in Assets/Scripts/PlayerController.cs"` from your CI script within the Unity project root.
04Parse Atlas Output: Capture the JSON event stream from stdout and parse it in a subsequent CI step to review the unified diffs and confirm modifications to your C# MonoBehaviour scripts.
05Run Unity Tests: After Atlas's modifications, execute `Unity Test Framework (NUnit)` tests from the command line to validate changes, for example, by running `Unity.exe -batchmode -runTests -testPlatform EditMode -projectPath . -logFile -quit`.
06Format Code: Apply `dotnet format` to any modified C# files to maintain code style consistency, using `atlas run --command "bash dotnet format Assets/Scripts/PlayerController.cs"` or a direct `dotnet format` call.
07Review and Commit: Review the generated git patches or diffs (Atlas snapshots file changes as git patches) and stage/commit changes if satisfactory, potentially using Atlas's git capabilities or standard CI tools.

Frequently asked questions

Can Atlas modify Unity .meta files or scene YAML in CI?: Atlas never touches .meta files or scene YAML without showing you first. In a headless CI environment, this means Atlas will not modify these critical Unity asset files unless explicitly configured and reviewed, ensuring project integrity.
How does Atlas handle Unity Package Manager (UPM) dependencies in CI?: Atlas can read your `Packages/manifest.json` and the packages resolved by the Unity Package Manager (UPM). This allows it to understand your project's dependencies when analyzing or modifying C# scripts, ensuring context-aware changes.
What Atlas tools are essential for Unity CI automation?: For Unity CI automation, essential Atlas tools to pre-approve include `read` for code analysis, `edit` for C# file modifications, and `bash` for executing external commands like `dotnet format` or Unity Test Framework (NUnit) via the command line.
How can I ensure Atlas's changes don't break Unity gameplay logic?: Atlas drafts a plan in a read-only plan agent before execution. In CI, you should always follow Atlas's changes with automated Unity Test Framework (NUnit) tests (EditMode and PlayMode) to validate that gameplay logic and MonoBehaviour lifecycle order remain correct.
Can Atlas help optimize MonoBehaviour performance in CI?: Yes, Atlas can be prompted to hoist GetComponent calls out of Update and cache them in Awake, reducing per-frame allocations. This optimization can be automated in CI, with Atlas applying the change to your MonoBehaviour scripts.
How do I specify the AI model for Atlas in a Unity CI pipeline?: You must explicitly set the model using the `--model provider/model` form, for example, `--model github/copilot-gpt-4`. This ensures Atlas uses the correct AI model for your Unity C# code analysis and generation tasks in CI.
What if an Atlas headless run needs user input for a tool?: If an Atlas headless run encounters a tool call that requires user input (an `ask` permission rule), the session will halt. For CI, all necessary tools must be pre-approved with `allow` rules in Atlas's permission configuration to ensure non-interactive execution.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Run Atlas Headless in CI with Atlas (2026 Workflow)

How to run Atlas headless in CI in 2026: atlas run sends one prompt and exits when the session goes idle, with --format json, --command, and --continue for pipeline steps.

Run the Unity Test Suite and Triage Failures with Atlas in 2026

In 2026, Unity developers use Atlas to efficiently run their Unity Test Framework (NUnit) suites and triage failures. Turn a wall of red output into a prioritized list of distinct root causes for C# gameplay code.

Review a Pull Request in Unity with Atlas in 2026

Review Unity pull requests with Atlas in 2026. Analyze C# gameplay code, catch MonoBehaviour lifecycle bugs, and ensure optimal framerate with Unity Test Framework (NUnit) and Unity Package Manager (UPM).

Locate Unity Behavior Implementations with Atlas in 2026

In 2026, Unity developers use Atlas to pinpoint behavior implementations. Discover exact C# files and symbols responsible for gameplay actions, leveraging Atlas's semantic search and LSP integration for your Unity

Refactor a legacy module in Unity with Atlas in 2026

Restructure old Unity C# modules without breaking callers using Atlas. Leverage Unity Test Framework (NUnit), UPM, and precise code mapping.

Research a Third-Party API for Unity Integration in 2026 with Atlas

Streamline Unity API integration in 2026. Atlas helps Unity developers research external APIs, fetch documentation, and verify code against `dotnet format` and `Unity Test Framework (NUnit)` standards before committing.

Diagnose a hanging or long-running command in Unity with Atlas in 2026

Diagnose and resolve hanging or slow Unity commands, like `dotnet format` or `Unity Test Framework (NUnit)`, with Atlas. Quickly identify if a process is genuinely slow or blocked on input, and get it unstuck.

Upgrade a Unity Dependency and Fix Breakage with Atlas in 2026

In 2026, Unity developers use Atlas to upgrade major dependencies, automatically fixing compile and test failures. Leverage Atlas to manage Unity Package Manager updates and repair C# code.

Browse this resource hub