An experiment in building games on Godot and its compatible forks (Redot, Blazium) with Claude Code using a deliberate pipeline instead of a chat box.
Most frameworks hand you a fixed toolbox. This one is designed to be broken, rebuilt, and replaced by you.
The agents self-improve from your experience: every bug, every awkward pattern, every moment where the pipeline slowed you down instead of helping is signal. The bug-triage, skill-researcher, and godot-refactor agents exist specifically to close that loop: find the friction, trace the root cause, update the skills, rewrite the rules. The framework you end up with is not the one you started with.
The tools are here. The shape of the framework is yours to decide.
✅ Foundation POC is complete and retired.
✅ FPS POC Part 1 completed.
Disclaimer: I don't have much time, so progress is slower than I'd like — but I'll keep the updates coming.
Latest: v0.2.1 — the self-improvement loop: /framework-feedback (conversation) +
/harvest-sessions (logs) feed the human-gated audit ledger; promote handles
already-in-plugin capabilities; token-audit fixes; modular settings. Full history in
Releases;
the reference game is on Itch.
Since v0.2.1 — background sub-agents can reach the async UI tools (task board, ask,
promote, asset) instead of auto-denying; mcp__ui__form is now foreground-only with
mcp__ui__ask as the background → task-panel channel; a tool-domain guard keeps
game-specific bots out of the shared plugin; a typed-export NodePath gate catches a silent
Godot null trap; Codex/Hermes can be set up from the Settings panel (one button, then
restart); and CI now runs the full validate + test gate, with the plugin manifest
riding the same release train as package.json.
Most AI-assisted game dev setups hand you a frontier model and a blank prompt. Describe your game, get some code, paste it in, pray it runs. That works, until you want to ship something repeatable, reviewable, and actually yours.
This project bets on a different loop: move the design decisions to before inference, not during it. You don't tell the model what to build; you go through a structured interview that cuts scope to one buildable slice, produces a locked design doc, and only then hands it off to a dev agent. The model stops guessing. You stop pasting broken code.
The pipeline looks like this:
idea → game-designer (interviews you, pushes back on vague scope, writes a one-page design doc)
→ godot-dev (implements exactly that doc, nothing more, nothing less)
→ godot-verify (headless engine checks, catches what Godot silently drops)
→ you (one look in the editor, that's your job)
Push-back is the product. The designer agent will not silently fill gaps. It asks, narrows, and confirms before anything gets built. Nothing gets reported "done" without passing real engine checks.
| Term | What it means |
|---|---|
| Xenodot | The ecosystem |
| Xenodot Forge | This framework: web UI + the agent workflow |
| Xenodots | The individual agents (designer, dev, refactor, researchers, triage) |
| Xenodot Hive | The multi-agent orchestrator: the main coordination loop |
ui/ Web UI (Node), run sessions from a browser.
Designer questions render as clickable forms.
Tool approvals become allow/deny buttons.
Live event feed so you see what's happening.
flowchart LR
subgraph Browser["browser — ui/client"]
UI["chat · activity · task board<br/>approval cards · FleetView"]
end
subgraph Server["Node server — ui/server"]
WS["WebSocket + HTTP<br/>core/index.js"]
SES["core/session.js<br/>permission gate · 529 retry<br/>detach / reattach"]
MCP["in-process MCP tools<br/>form · ask · tasks · promote"]
end
subgraph SDK["Claude Agent SDK session"]
HIVE["Hive orchestrator<br/>ui/orchestrator.md — routes, never implements"]
SUBS["sub-agents: designer · builders<br/>playtester · researchers"]
end
PLUGIN["xenodot plugin (plugin/)<br/>agents · skills · hooks · tools · library"]
GATES["deterministic gates<br/>validate.sh floor · playgrade.sh rubric<br/>(one shared checks lib)"]
GAME["your Godot game<br/>(its own repo — read in place)"]
HERMES["Hermes — optional researcher"]
CODEX["Codex — optional reviewer"]
UI <--> WS --> SES --> HIVE
SES --- MCP
HIVE --> SUBS
PLUGIN -. "loaded via SDK plugins option" .-> HIVE
SUBS -- "build / play" --> GAME
SUBS -- "must pass" --> GATES --> GAME
HERMES -.-> HIVE
CODEX -.-> HIVE
The framework is independent of your game, it contains no game folder. It
points at your Godot project wherever it lives (by default a sibling folder named
game/), reads it in place, and never tracks it. Your project stays in its own git
repo; the framework drives Claude Code against it.
The full capability catalog lives in FEATURES.md — agents, skills, the web UI, verification, autonomous mode, and integrations. How it ships (the plugin vs. game separation) is in What ships below. The reference project during this POC is DiceOfFate.
- Claude Code installed and authenticated
- A Godot-family engine 4.x: Godot, Redot, or Blazium (skills target 4.x APIs; verified against 4.6). The forks share Godot's project format, GDScript and CLI, so they run the same pipeline unchanged, see docs/engines.md.
- Node.js 18+ (only for the web UI)
Separate bills, by design — only the Hive is required. The Hive (orchestrator + sub-agents) runs on your local Claude Code login. Hermes (optional researcher) and Codex (optional reviewer) are separate runtimes, each with its own provider and billing.
| Rail | What runs | How you pay | Switch it |
|---|---|---|---|
| Hive (required) | Claude Code via the Agent SDK, pinned to Opus 4.8 | Claude subscription (Pro ~$20 / Max |
subscription: claude /login; API key: set ANTHROPIC_API_KEY |
| Hermes (optional) | External Hermes Agent, model of your choice | Provider it points at — OpenRouter / Nous Portal / your own key, metered per token (~$0.25–$2.50 per deep run) | install + setup: HERMES.md; then ⚙ Settings or npm run hermes |
| Codex (optional) | OpenAI's Codex reviewer (/codex:review), on-demand |
a ChatGPT subscription with Codex access (Plus / Pro / Business) or an OpenAI API key — billed to your OpenAI account | setup: CODEX.md (npm run codex:setup + codex login); ⚙ Settings → Codex |
- Your Anthropic plan covers only the Hive. Hermes and Codex each bring their own account and billing — Hermes always needs its own API key; Codex bills to your ChatGPT/OpenAI account.
- Codex on a plain ChatGPT subscription. A Plus (or higher) plan with Codex access works — no separate API key needed. On a ChatGPT login, point Codex at a general model (
gpt-5.5), not a*-codexvariant (those are rejected). Details inCODEX.md. - Hermes and Codex are off by default; the framework runs fully on the Hive alone.
- You can point the Hive at the Anthropic API (or a compatible endpoint) via env vars instead of the subscription login. I don't — a subscription beats an API key for heavy use; API keys are better for ad-hoc requests.
Disclaimer (maintainer's setup): I run on paid AI subscriptions across providers (~$150/mo) because I work across several projects, so the flat fee pays off. That is not required — the framework runs on Pro, on pay-per-token API, or with the optional rails off entirely. If you want a cheaper setup, open an issue and I'll help you wire one.
The framework and your Godot game are two separate repos, side by side (recommended, not required — any path works):
your-workspace/
├── xenodot-forge/ ← this framework (cloned)
└── game/ ← your Godot project (any name; its own git repo)
-
Clone the framework and install:
git clone https://github.com/arthur0n/xenodot-forge.git cd xenodot-forge && npm install
-
Point it at your game. Scaffolds a new runnable project if the path doesn't exist, or wires an existing one in place (and remembers it):
npm run new -- ../game # any path works: ../game, /abs/path, ../nested/project -
Run the web UI:
npm start # http://localhost:8338
Every command runs from inside xenodot-forge/ and takes the game path as an argument, so your game can be named anything and live anywhere. Re-check wiring anytime with npm run doctor -- <path>.
Open Claude Code in your workspace and paste this:
Read https://raw.githubusercontent.com/arthur0n/xenodot-forge/main/README.md and follow its
Quickstart to set up and run it against my Godot game at: <PATH TO MY GODOT GAME>. Run the
commands yourself, fix anything that fails, and tell me when it's running.
Install the plugin once (npm run doctor prints the exact commands), then run claude from your game folder:
/plugin marketplace add /path/to/xenodot-forge
/plugin install xenodot@xenodot-forge
Your game lives in its own repo, so pulling the latest framework never touches your work:
cd xenodot-forge && git pullThe framework's Claude Code setup is in two parts:
- Framework spine (
.claude/), rules + the rtk hook for working on the framework (the Node/TS web UI). Committed; nothing to install. - The xenodot plugin (
plugin/), the agents,godot-*skills, the game-agnostic verification tools (the validate gate, verify/gen scripts), safety + token hooks (game sessions auto-route Bash through rtk when it's installed, and repeat byte-identical Reads are deduped), and the knowledge base (library/). The single source of truth for what a game gets. The web UI loads it via the Agent SDKpluginsoption; terminal Claude Code installs it once from the bundled marketplace (.claude-plugin/marketplace.json). Capabilities namespace asxenodot:<name>.
Nothing is copied into your game. The only per-game files the framework materializes are
gitignored and regenerated on demand: tools/ (copied, Godot runs .gd helpers from
res://) and library/ (a symlink to the plugin's knowledge base). Your committed game
stays pure game.
Example assets stay out of your game. Free CC0 models/textures live in an external
x-shared-assets/ library, mounted into the game as a gitignored symlink Godot imports
(res://x-shared-assets/). Override its location with assetLibrary in .xenodot.json; you
place files into the game or the shared library from the Get Assets modal. See
FEATURES.md.
Growing the framework. New skills/agents/tools start game-local in <game>/.claude/
and are usable immediately; you promote the keepers into the plugin
(npm run promote -- skills <name>). The clone → new → run path is guarded by
npm run test:onboarding (and CI). Full growth loop in FEATURES.md.
The digital-twin domain moved to its own product. What started here as an experimental
second plugin grew into xenodot-twin — a
digital-twin 3D viewer (BIM/IFC import, master-data join, live time-series overlays), forked
from this framework and kept in sync via its /sync-upstream flow.
The web UI runs the same agents from a browser (full feature list in FEATURES.md):
cd xenodot-forge
npm start # foreground — opens http://localhost:8338 (Ctrl-C to stop)Run it detached (survives the terminal; PID + log under .xenodot-run/, reclaims the
port if a stale server holds it):
./start_server # the configured game; ./start_server /path/to/game to override
./stop_server # stop it; PORT=9000 ./start_server for a different portnpm run new (or npm run setup) already saved your game's path to .xenodot.json
(gitignored), so npm start finds it with no arguments. The framework only
reads your project, it stays in its own repo.
You can point at any project, no setup needed:
npm start /path/to/another/project # one-off override
GAME_DIR=/path/to/project npm start # via environment variablePath resolution order (first match wins): CLI argument → GAME_DIR env var →
saved .xenodot.json → default sibling ../game.
Troubleshooting, opens but shows no sessions or files? The UI is pointed at
a folder with no project.godot. The server prints a warning on start and the
sidebar shows how to fix it. Point it at your game and restart:
npm run setup -- /path/to/your/game- Small slices. A design doc is done when a single agent task can implement it and verification plus one human look can confirm it.
- Push-back is the product. The framework should refuse to silently fill vague briefs with its own assumptions. If the scope isn't clear, it asks.
- Verification is mandatory. Godot exits 0 on script parse errors and silently drops unknown
.tscnproperties.tools/verify_scene.gdexists because bugs that should have been caught shipped "verified" without it. - You stay the designer. The framework keeps the loop fast and honest, it does not replace your judgement on what game to build.
If you're here to judge the agentic engineering, read these four things in order:
ui/orchestrator.md— the Hive's system prompt: routing rules with named anti-patterns, judge≠fixer, the bounded regrade loop.ui/server/core/session.js— the layered permission gate (makeCanUseTool) and how the Agent SDK session is wired (plugin, in-process MCP tools, reconnect/detach).plugin/tools/validate.sh+plugin/tools/playgrade.sh— builder floor and evaluator rubric sourcing one shared check library, so the generator and the judge can't drift apart.docs/process/self-improvement.md— the human-gated audit loop: three ways findings enter the ledger, zero ways they auto-apply.
This framework isn't trying to beat Claude Code, Hermes, or any model provider. It's built to use them under the hood, with you still holding the wheel. The bet isn't "our agent vs theirs", it's "the right tools composed behind one honest, human-gated loop."
- Bring your own provider. The Hive drives Claude Code through the Agent SDK, so Bedrock / Vertex / Foundry / enterprise gateways are first-class backends and non-Claude models route through an Anthropic-compatible proxy — you're tied to an API shape, not a vendor. (Setup details in FEATURES.md.)
- Other agents as delegated workers, not bosses. The Hive stays the orchestrator and you keep approving its moves; a persistent agent like Hermes plugs in underneath as a sub-agent the Hive dispatches to (over Hermes's OpenAI-compatible HTTP API), useful for work outside Godot's core: long-running memory, web research, multi-step ops. Anything it produces re-enters the same verification gates before it counts as done. (Running such an agent on top as the conductor is possible too, but only on a leash that checkpoints with you, we compose autonomy, we don't surrender it.)
- The one rule that doesn't bend: human in the loop. Every other piece, provider, model, outer orchestrator, is swappable. The approval gates, the designer interview, and the human-run
promoteare not.
No spin. Where it's weak today, and the intended direction, marked clearly as not yet shipped:
- The learning loop is deliberately manual. Skills improve only when you run
promote. That's the point, you stay the gatekeeper, but knowledge accrues slower than auto-capturing agents like Hermes. Direction: assisted capture that drafts the skill and still waits for your yes. - API-shape lock-in. Native backends are all Claude-family (Bedrock / Vertex / Foundry / gateway); other models need a translating proxy and lose some tool-use fidelity, since the pipeline is tuned for Claude's tool calls. Direction: first-class, UI-level provider switching, with the fidelity gap measured honestly instead of hidden.
- Hermes worker bridge is early (POC). The Hermes-as-sub-agent story above is now shipped as a gated POC: a small in-process tool (
mcp__ui__hermes) wraps Hermes's HTTPrunsAPI (Hermes is an MCP client, not yet a server), every dispatch passes the human approval gate, and Hermes stays purely advisory — it investigates, a Xenodot researcher + you own the verdict and the library write. Off by default; setup is inHERMES.md. Still open: proving its research actually beats the native researcher on real gaps, and a single source of truth for skills/memory aligned to the agentskills.io standard so two systems don't grow two brains. - No persistent cross-session memory of you. Each run starts fresh against the game repo; it doesn't remember your preferences the way an always-on agent does. Direction: an optional, human-curated memory layer, off by default.
- Verification is Godot-specific and headless-bound. The gates catch what the engine silently drops, but render checks are shallow and there's no gameplay/behavioral testing yet. Direction: deeper runtime assertions.
- Local, single-user, not always-on. The web UI is one person at one machine, no multi-channel, no 24/7. That's by design (human in the loop), but a real limit if you wanted hands-off automation, which this deliberately is not for.
- It's a POC, and narrow. Godot-family only; APIs, layouts, and prompts change without notice. Direction: stabilize the pipeline contract before chasing breadth.
Git tags are the source of truth, in a 4-part scheme keyed to the change type:
feat→ new sub-version:v0.1.2→v0.1.3fix/chore/refactor→ new build:v0.1.2→v0.1.2.1
When you commit in a terminal, the pre-commit hook asks whether to cut a
release. Pick a type and it bumps package.json and tags the commit; press enter
to skip. Agent/CI commits (no TTY) are never prompted.
Tags are created locally, push them yourself:
git push origin main
git push origin v0.1.3For a scripted / non-interactive release, stage the bump into your next commit:
npm run release -- feat # or: fix | chore | refactor
git commit -m "…"
8BD0
# post-commit creates the tagpackage.json tracks the 3-part sub-version; the 4th build digit lives only in
the git tag (npm versions must be valid 3-part semver).
The plugin is the framework. Changes under
plugin/(agents, skills, tools, the knowledge base) ARE framework changes, list them in release notes as normal. Game-specific capabilities stay game-local until younpm run promotethem into the plugin.
Not accepting contributions for now, issues and PRs are unlikely to be reviewed. Fork freely; it's MIT.
This project doesn't exist in a vacuum. These people and projects shaped how it thinks about AI-assisted workflows, skill design, and Godot tooling.
Matt Pocock, the idea that skills should be procedures, not references. One canonical path, observable outcomes, no ambiguity about what "done" means.
Eduardo Schildt, game designer and artist who loves making games and shares what he learns through game dev tutorials.
Brackeys, Top-quality game development tutorials on everything from Unity, Godot and programming to game design. A reminder that clarity and enthusiasm aren't mutually exclusive.
Jan Mesarč, GodotPrompter, the most complete Godot × Claude Code library out there: ~48 skills covering 2D, 3D, UI, audio, multiplayer, C#, optimization and more, plus 9 specialized agents. Parts of this project's plugin scaffolding are adapted from it (MIT, with thanks). If you want broad Godot coverage for Claude Code today, use GodotPrompter, it's excellent.
This project is not a competitor on breadth. The differences are in philosophy:
| GodotPrompter | Xenodot Forge | |
|---|---|---|
| Scope | Broad reference library (48+ skills) | Narrow pipeline with a locked design step |
| Skill style | Reference: variants + trade-offs, GDScript and C# | Procedure: one canonical path, GDScript only |
| Entry point | Skills you invoke directly | Designer interview gates what gets built |
| Verification | Code-review checklists | Observable runtime gates + error→fix tables |
| Growth rule | n/a | One skill at a time, adopted after passing its gate on a real project |
If you want broad coverage now, go use GodotPrompter. If you want to experiment with the pipeline model on your own project, clone this.