{"slug": "run-parallel-ai-agents-on-one-godot-project-without-breaking-each-other-s-work", "title": "Run parallel AI agents on one Godot project without breaking each other's work", "summary": "Ziva.sh published a guide showing that parallel AI coding agents can work on a single Godot project without overwriting each other by giving each agent its own git worktree, copying the hidden .godot import cache into it, and adding an override.cfg so each copy saves to its own user:// folder. Ziva.sh tested the setup in November 2026 with Godot 4.7.2 and git 2.56.0 on Linux in a 300-image project called Shop Demo, where two simulated agents added a shop screen and a settings menu and the copied cache eliminated the \"(Re)Importing Assets (300 steps)\" reimport step. Ziva.sh notes that project.godot is expected to conflict when branches are merged back one at a time, and that Windows and macOS were not tested.", "body_md": "# Run parallel AI agents on one Godot project without breaking each other's work\n\nGive 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.\n\nZiva.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.\n\n## [What breaks when agents share a Godot project](#what-breaks-when-agents-share-a-godot-project)\n\nGit worktrees solve the obvious problem: two agents editing the same files in the same folder. Godot adds four more:\n\n- **Every copy reimports your assets.** Git ignores the`.godot` folder, so a new checkout has no import cache.\n- **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.\n- **`project.godot` collects shared settings.** Autoloads and input actions from two agents land in the same section of the same file.\n- **Agents report \"it works\" without running the game.** Ask for a video.\n\n## [1. One worktree per agent](#1-one-worktree-per-agent)\n\nRun 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.\n\nEach 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.\n\nClaude 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.\n\n## [2. Copy the import cache](#2-copy-the-import-cache)\n\nOn 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.\n\n## [3. Give each copy its own save folder](#3-give-each-copy-its-own-save-folder)\n\nWithout an override, all three folders saved to the same place:\n\nOur 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.\n\nCreate a file named `override.cfg` in the root of each copy, next to `project.godot`, with a different name in each:\n\nGodot reads `override.cfg` on top of `project.godot`, and the name may contain a `/` to group the folders. Run each copy again:\n\nYour 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`.\n\n`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`.\n\n## [4. Let the agents work, then commit](#4-let-the-agents-work-then-commit)\n\nGive 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:\n\nIn 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`.\n\nIf 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.\n\n## [5. Record a video of each change](#5-record-a-video-of-each-change)\n\nGodot's Movie Maker mode records a run to a file:\n\nGodot 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.\n\n`--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.\n\nA 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).\n\n## [6. Merge back](#6-merge-back)\n\nMerge one branch at a time from your main folder:\n\nThe first merge was a fast-forward. The second stopped on `project.godot`, because both agents added an autoload under `[autoload]`:\n\nKeep both lines and delete the conflict markers:\n\nThen finish the merge and check that the game still loads:\n\nGodot printed no errors, and both autoloads loaded.\n\n## [7. Clean up](#7-clean-up)\n\n`git worktree remove` worked without `--force`, because `override.cfg` and `.godot` are ignored. The save folders live outside the project, so delete them yourself.\n\n## [Where Ziva's Parallel mode does these steps for you](#where-zivas-parallel-mode-does-these-steps-for-you)\n\n[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:\n\n- 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.\n- Agents can't overwrite your game's save files.\n- 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.\n- 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.\n- It ends with a playtest of the whole game.\n\nParallel 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.\n\n## [Related reading](#related-reading)\n\n- [Parallel AI agents in Ziva (Parallel mode)](https://ziva.sh/docs/parallel-mode) : how to start, review and undo a part\n- [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\n- [How to automate playtesting in Godot](https://ziva.sh/blogs/godot-automated-playtesting) : bots, MCP servers and AI agents\n- [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", "url": "https://wpnews.pro/news/run-parallel-ai-agents-on-one-godot-project-without-breaking-each-other-s-work", "canonical_source": "https://ziva.sh/blogs/parallel-ai-agents-godot", "published_at": "2026-11-22 00:00:00+00:00", "updated_at": "2026-11-22 16:14:39.769967+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Godot", "Godot 4.7.2", "git 2.56.0", "Claude Code", "Codex CLI", "Shop Demo"], "also_reported_by": [], "takeaway": "Give each parallel agent its own git worktree, copy the .godot import cache into it to skip reimporting all 300 assets, and add an override.cfg to give each copy a separate user:// save folder.", "recommendation": {"advice": "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.", "playbook": "agent-architecture", "playbook_url": "https://wpnews.pro/playbooks/agent-architecture"}, "alternates": {"html": "https://wpnews.pro/news/run-parallel-ai-agents-on-one-godot-project-without-breaking-each-other-s-work", "markdown": "https://wpnews.pro/news/run-parallel-ai-agents-on-one-godot-project-without-breaking-each-other-s-work.md", "text": "https://wpnews.pro/news/run-parallel-ai-agents-on-one-godot-project-without-breaking-each-other-s-work.txt", "jsonld": "https://wpnews.pro/news/run-parallel-ai-agents-on-one-godot-project-without-breaking-each-other-s-work.jsonld"}}