claudeers.
// Automation & Workflows

godot-agent-harness

Multi-agent harness for Godot 4.7 games: Claude Code integrates, Codex does logic+tests, Antigravity does visuals. Worktrees, headless tests, in-game screens…

// Automation & Workflows[ cli ][ api ][ web ][ mobile ][ claude ]#claude#ai-agents#claude-code#codex#gdscript#godot#automation◷ NOASSERTION$open-sourceupdated 14 days ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up godot-agent-harness (git-clone project) into my current project.
Found on https://claudeers.com/godot-agent-harness
Repo: https://github.com/caiizilaz/godot-agent-harness
Homepage/docs: —
Detected install method: git-clone → git clone https://github.com/caiizilaz/godot-agent-harness
Category: automation. Platforms: cli, api, web, mobile.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or clone
git clone https://github.com/caiizilaz/godot-agent-harness

// compatibility

Platformscli, api, web, mobile
Operating systems—
AI compatibilityclaude
LicenseNOASSERTION
Pricingopen-source
LanguageGDScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Godot Agent Harness

A small, tested setup for building a Godot 4.7 game with several AI coding agents at once: Claude Code integrates, Codex writes logic and tests, Antigravity handles visuals. Each agent works in its own git worktree, edits only the files its brief owns, and nothing merges without the headless test suite passing.

It came out of a real game, KLAP CHAT: Reroll Protocol, where three agents merged 133 PRs in four days. Everything here fixed a problem that actually happened; nothing is here "in case".

ภาษาไทย: ชุดตั้งต้นสำหรับทำเกม Godot 4.7 ด้วย AI หลายตัวพร้อมกัน (Claude Code รวมงาน, Codex ทำตรรกะ+เทสต์, Antigravity ทำงานภาพ) แต่ละตัวทำงานใน worktree ของตัวเอง แก้เฉพาะไฟล์ที่บรีฟให้ และรวมงานได้เมื่อเทสต์ผ่านเท่านั้น

What you get

PieceWhat it stops
tools/test.shGodot crashing mid-import and the suite then logging one error for 10+ minutes. Retries the import, checks every imported file exists, caps time and log size.
tests/run_tests.gdAgents editing the same "list of suites" lines. Finds tests/test_*.gd itself, counts SCRIPT ERRORs as failures, shards for CI (TEST_SHARD=2/4).
tools/lint.sh + .githooks/pre-commitLint passing locally and failing in CI. Pinned gdlint in a cached venv, run on staged files.
tools/shot.sh"Tests are green" on a screen nobody looked at. Runs a scene in a real window, saves a PNG, fails on runtime errors or a blank frame.
docs/engine-reference/godot/Agents writing Godot 4.3 APIs. Breaking changes and renamed APIs for 4.4 → 4.7.
docs/agents/STATUS.md + tests/test_status_board.gdA task board that lies. CI fails if a merged task stays on the board, a task is blocked on finished work, or a brief link is dead.
docs/decisions.md + tests/test_decisions_index.gdAgents reading 40 KB of decisions. One-line index at the top; CI keeps it complete.
tools/agents/new-worktree.shTwo agents in one checkout. One task = one worktree = one branch, imported and ready to test.
tools/ci/flaky.shRe-running red CI until it passes. Lists tests that failed across recent runs.
CLAUDE.md, AGENTS.md, .claude/rules/, .agent/Each agent getting the rules it needs: Claude Code (integrator, path-scoped rules), Codex (AGENTS.md), Antigravity (.agent/rules + /start-task, /finish-task).

Start

Needs: Godot 4.7 on PATH as godot (or GODOT=/path/to/godot), Python 3.11+, bash and perl; the gh CLI only for tools/ci/flaky.sh and the template command below.

PlatformStatus
macOSUsed daily by the project this came from; every command below was run here.
LinuxShould work (CI targets ubuntu-latest), but the workflow has not yet run green on GitHub: Actions was blocked by an account billing issue when this was written. tools/shot.sh needs a display; on a headless machine try xvfb-run -a tools/shot.sh ... (not tested here).
WindowsNot supported natively (bash scripts). Use WSL.
gh repo create my-game --template caiizilaz/godot-agent-harness --private --clone
cd my-game
git config core.hooksPath .githooks
tools/lint.sh && tools/test.sh        # 6/6 passed on a fresh clone
tools/shot.sh main shots/main.png     # opens a window, saves the frame

Then:

  1. Replace scripts/core/Score.gd, scripts/Main.gd and scenes/Main.tscn with your game; keep rules in pure code so tests can run them.
  2. Pick your Godot version once, in tools/ci/godot-version.txt (exact, e.g. 4.7.2). CI installs exactly that, with the download's SHA-512 checked. tests/test_engine_version.gd fails until project.godot, docs/engine-reference/godot/VERSION.md and the installed editor agree.
  3. Write your own decisions into docs/decisions.md (keep the index row for each).
  4. Hand out work: write a brief from docs/agents/tasks/_TEMPLATE.md, add a row to STATUS.md, then tell the agent:
    • Codex: Read AGENTS.md and docs/agents/tasks/CX-1.md, then do the task.
    • Antigravity: open the repo as the workspace and run /start-task AG-1 (workflows are in .agent/workflows/).
    • Claude Code: it reads CLAUDE.md by itself; ask it to merge the agent's branch when the report arrives.

The example task CX-1 is ready to try with Codex.

Board prefixes

tests/test_status_board.gd only recognises task ids that start with AG-, CX- or C-. A row with any other prefix (say GM-4) is ignored, not flagged. To use your own, edit the one list ID_PREFIXES at the top of that file and use the same prefixes in STATUS.md and the brief file names.

If GitHub Actions does not start

A job that dies in two seconds with "recent account payments have failed" is a billing problem, not your code. Run tools/lint.sh && tools/test.sh on the branch merged with origin/main, say so in the PR, and merge on that. (CLAUDE.md makes this the integrator's rule.)

ภาษาไทย: เริ่มใช้งาน

  • ต้องมี: Godot 4.7 (คำสั่ง godot), Python 3.11+, bash, perl · macOS ใช้ได้เต็มที่ · Linux น่าจะใช้ได้แต่ CI ยังไม่เคยรันผ่านบน GitHub · Windows ใช้ผ่าน WSL
  • สร้างโปรเจกต์: gh repo create my-game --template caiizilaz/godot-agent-harness --private --clone แล้วรัน git config core.hooksPath .githooks
  • เช็กว่าพร้อม: tools/lint.sh && tools/test.sh ควรได้ 6/6 · tools/shot.sh main shots/main.png เปิดหน้าต่างเกมแล้วเซฟภาพ
  • สั่ง agent: เขียนบรีฟจาก docs/agents/tasks/_TEMPLATE.md และเพิ่มแถวใน STATUS.md
    • Codex: Read AGENTS.md and docs/agents/tasks/CX-1.md, then do the task.
    • Antigravity: เปิด repo เป็น workspace แล้วพิมพ์ /start-task AG-1
    • Claude Code: อ่าน CLAUDE.md เอง สั่งให้รวม branch เมื่อ agent ส่งรายงาน
  • รหัสงานที่เทสต์บอร์ดรู้จัก: AG-, CX-, C- เท่านั้น ถ้าใช้ prefix อื่นต้องแก้ ID_PREFIXES ในไฟล์ tests/test_status_board.gd ไม่งั้นแถวนั้นจะถูกข้ามเงียบๆ
  • ถ้า GitHub Actions ไม่เริ่มทำงานและขึ้นเรื่องการจ่ายเงิน: ไม่ใช่บั๊กของโค้ด ให้รัน lint กับเทสต์ในเครื่องแทน แล้วระบุใน PR

How a task flows

user decides ─▶ Claude writes brief + STATUS row ─▶ agent: new-worktree.sh → work → tests → report → commit
      ▲                                                                                        │
      └──── Claude: merge origin/main into branch, read diff, PR, merge on green, archive ◀──────┘

Details in docs/agents/README.md. Rules per agent: CLAUDE.md, AGENTS.md.

Built for a real game: KLAP CHAT: Reroll Protocol

This harness was extracted from the project that made it necessary: KLAP CHAT: Reroll Protocol, a Thai-mythology turn-based strategy roguelite growing into a 3v3 MOBA, made in Godot with Claude Code, Codex and Antigravity working in parallel. The game is in development and its source repository is private; its public pages (in Thai first):

What that project looked like when this was written (counted from its git history, 5 Nov 2026):

Merged PRs133, between 1 and 5 November 2026
Commitsabout 715; about 105 carry Agent: codex, about 104 Agent: antigravity, the rest are Claude Code's
Tests801 headless tests in 166 suites, all passing locally when the last PR merged

What went wrong along the way, and the piece that now stops it:

What happenedFix in this repo
Godot crashed mid-import and the suite then printed one error for 10+ minutestools/test.sh
Parallel branches kept conflicting on the hand-written list of test suitestests/run_tests.gd finds suites itself
The task board said tasks were ready after they merged, and blocked on work that was finishedtests/test_status_board.gd
One test compared two runs that started a second apart; another had a 90 s budget that slow CI runners missedthe determinism and CI-time rules in .claude/rules/tests.md, and tools/ci/flaky.sh
GitHub Actions stopped on a billing problem while PRs kept mergingthe local-verification rule in CLAUDE.md
A screen passed every test and nobody had looked at ittools/shot.sh
The CI workflow pointed at a version file that had not been copied into the templatetests/test_engine_version.gd now checks CI only names files that exist

The last row happened while writing this README: the new test failed on the template itself.

Using only one agent

Everything still works with Claude Code alone: skip the briefs and the board, keep tools/, tests/, docs/engine-reference/ and the checks in CLAUDE.md.

Compared with bigger frameworks

Frameworks such as Claude-Code-Game-Studios model a whole studio (49 agents, 74 skills). This harness is the opposite bet: few files, enforced by tests rather than prose, and built for different AI tools working side by side. The Godot engine reference here comes from that project (MIT).

License

MIT. docs/engine-reference/godot is MIT from Claude-Code-Game-Studios; see its licence file.

// faq

What is godot-agent-harness?

Multi-agent harness for Godot 4.7 games: Claude Code integrates, Codex does logic+tests, Antigravity does visuals. Worktrees, headless tests, in-game screenshot check.. It is open-source on GitHub.

Is godot-agent-harness free to use?

godot-agent-harness is open-source under the NOASSERTION license, so it is free to use.

What category does godot-agent-harness belong to?

godot-agent-harness is listed under automation in the Claudeers registry of Claude-compatible tools.

13 views
★ 10 stars
unclaimed
updated 14 days ago

// embed badge

godot-agent-harness on Claudeers
[![Claudeers](https://claudeers.com/api/badge/godot-agent-harness.svg)](https://claudeers.com/godot-agent-harness)

// retro hit counter

godot-agent-harness hit counter
[![Hits](https://claudeers.com/api/counter/godot-agent-harness.svg)](https://claudeers.com/godot-agent-harness)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 264,763◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 110,676◷ MIT[ claude ]
→ see how godot-agent-harness connects across the ecosystem