# Run parallel AI agents on one Godot project without breaking each other's work

> Source: <https://ziva.sh/blogs/parallel-ai-agents-godot>
> Published: 2026-11-22 00:00:00+00:00

**Recommendation:** Isolate parallel coding agents in separate git worktrees with a copied .godot cache and a per-copy override.cfg save path, then merge branches one at a time and expect project.godot conflicts.
More in the playbook "Designing agent systems": <https://wpnews.pro/playbooks/agent-architecture>

# Run parallel AI agents on one Godot project without breaking each other's work

Give each agent its own git worktree, a second checkout of your repository in another folder, and treat that folder as its own Godot project. Copy the hidden `.godot` folder into it so Godot doesn't reimport every asset, and add an `override.cfg` so the copy's game saves to its own `user://` folder. Have each agent record a short video of its change, then merge the branches back one at a time. Expect `project.godot` to conflict.

Ziva.sh publishes this page and makes Ziva. We ran every command on this page in November 2026 with Godot 4.7.2 and git 2.56.0 on Linux, in a small test project named Shop Demo with 300 images. Two simulated agents added a shop screen and a settings menu. We ran Godot with `--headless` or under `xvfb-run`, never in a window. We did not test Windows or macOS.

## [What breaks when agents share a Godot project](#what-breaks-when-agents-share-a-godot-project)

Git worktrees solve the obvious problem: two agents editing the same files in the same folder. Godot adds four more:

- **Every copy reimports your assets.** Git ignores the`.godot` folder, so a new checkout has no import cache.
- **Every copy shares one save folder.** Godot names`user://` after the project name, so a test run in one copy can load or overwrite the save files of another.
- **`project.godot` collects shared settings.** Autoloads and input actions from two agents land in the same section of the same file.
- **Agents report "it works" without running the game.** Ask for a video.

## [1. One worktree per agent](#1-one-worktree-per-agent)

Run this in your project folder. Your `.gitignore` should already list `.godot/`; add `override.cfg` before you make the worktrees, so the file you add in step 3 is never committed.

Each folder is a full checkout on its own branch. Start Claude Code or Codex in one folder per agent, and open each folder as its own project in Godot's Project Manager if you want to watch it.

Claude Code (2.1.318) and Codex CLI (0.163.0) also have a `--worktree` flag that makes the worktree for you. Claude Code puts it in `.claude/worktrees/` inside your project. Godot skips folders that start with a dot: in our test, a full copy of the project under `.claude/worktrees/` added nothing to the main project's import, even with a duplicate `class_name`. The steps below still apply to that folder.

## [2. Copy the import cache](#2-copy-the-import-cache)

On a worktree without the copied `.godot` folder, Godot printed `(Re)Importing Assets (300 steps)` and reimported every image. With the copy, it printed no reimport step. Our 300 images imported in seconds either way; the saving grows with the size of your project. Commit the `.import` files Godot writes next to your assets, so every copy uses the same import settings.

## [3. Give each copy its own save folder](#3-give-each-copy-its-own-save-folder)

Without an override, all three folders saved to the same place:

Our test scene prints `OS.get_user_data_dir()` from `_ready()`; we shortened the home folder to `~`. Add the same `print` to your main scene to check yours.

Create a file named `override.cfg` in the root of each copy, next to `project.godot`, with a different name in each:

Godot reads `override.cfg` on top of `project.godot`, and the name may contain a `/` to group the folders. Run each copy again:

Your main folder keeps its usual save folder. Both copies also ran their games at the same time, each saving to its own folder. On Windows and macOS, [Godot's docs](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html) put the folder in `%APPDATA%` and `~/Library/Application Support`.

`git status` in each copy stayed empty after we started a headless Godot editor on it, so `override.cfg` and `.godot` stay out of the agent's commits. If a copy still uses the shared folder, look for `Error parsing` and `override.cfg` in Godot's output: with a broken line, our copy fell back to another folder. Also check that `application/config/disable_project_settings_override` is off in your project settings; when it's on, Godot ignores `override.cfg`.

## [4. Let the agents work, then commit](#4-let-the-agents-work-then-commit)

Give each agent one task in its own folder. When it's done, open the copy once, or run `--import` on it, so Godot writes the `.uid` files for new scripts, and commit those too:

In our test, the shop agent's commit had `shop.gd`, `wallet.gd`, their `.uid` files, a changed `main.tscn` and a new autoload in `project.godot`.

If your agent drives the Godot editor through an MCP addon, each copy needs its own open editor. If the addon listens on a fixed port, only one editor can use it at a time.

## [5. Record a video of each change](#5-record-a-video-of-each-change)

Godot's Movie Maker mode records a run to a file:

Godot printed `300 frames at 60 FPS (movie length: 00:00:05:00)`. A relative path is relative to the project folder, so the video landed in `../videos` next to the copies. Record your main folder the same way before you merge to get a "before" video.

`--write-movie` crashed with `--headless` in Godot 4.7.2 (`Program crashed with signal 11`, empty file). `xvfb-run` gives Godot a virtual screen on Linux. We did not test Windows or macOS; there, without Xvfb, Godot needs a window to record.

A video shows that the game starts and what the change looks like. It doesn't replace a test that checks the result, such as a [GUT or GdUnit4 input test](https://ziva.sh/blogs/godot-gut-gdunit4-simulate-input).

## [6. Merge back](#6-merge-back)

Merge one branch at a time from your main folder:

The first merge was a fast-forward. The second stopped on `project.godot`, because both agents added an autoload under `[autoload]`:

Keep both lines and delete the conflict markers:

Then finish the merge and check that the game still loads:

Godot printed no errors, and both autoloads loaded.

## [7. Clean up](#7-clean-up)

`git worktree remove` worked without `--force`, because `override.cfg` and `.godot` are ignored. The save folders live outside the project, so delete them yourself.

## [Where Ziva's Parallel mode does these steps for you](#where-zivas-parallel-mode-does-these-steps-for-you)

[Ziva](https://ziva.sh/docs), our AI agent inside the Godot editor, can run parallel AI agents on one request: pick [Parallel mode](https://ziva.sh/docs/parallel-mode), added in [Ziva 3.3.8](https://ziva.sh/changelog) (November 2026). It does the steps above for you:

- Each agent works on its own copy of your project in a background Godot editor, so your editor stays free. Copies reuse your import cache, so your assets aren't reimported from scratch.
- Agents can't overwrite your game's save files.
- Each finished part comes with a video of Ziva playing it and a list of what changed. When an existing screen changes, the video shows before and after side by side.
- Finished parts go into your project on their own. If you edit the same file meanwhile, the agent merges both changes and plays it again. To change a part, open it and click **Request changes** ; to remove it, ask to undo it.
- It ends with a playtest of the whole game.

Parallel mode is in Godot on Ziva's Pro and Ultra plans. The copies, background editors and videos stay on your computer; the agents send what they read and their screenshots to the AI model, as in any Ziva chat. Keep Godot open while it works; there's no headless or CI mode.

## [Related reading](#related-reading)

- [Parallel AI agents in Ziva (Parallel mode)](https://ziva.sh/docs/parallel-mode) : how to start, review and undo a part
- [How to simulate keyboard and mouse input in GUT and GdUnit4](https://ziva.sh/blogs/godot-gut-gdunit4-simulate-input) : tests each agent can run headless
- [How to automate playtesting in Godot](https://ziva.sh/blogs/godot-automated-playtesting) : bots, MCP servers and AI agents
- [Claude Code tips for large projects](https://ziva.sh/blogs/claude-code-tips-large-projects) : how we run Claude Code in parallel on Ziva itself
