Headless Game Development with Claude Code and Godot

How well do Claude Code and Godot work together for game development?

This is a learning project. I wanted to answer: How well do Claude Code and Godot work together for game development?

The experiment: Build a visual novel using Claude Code as the primary development interface — an autonomous collaborator that could analyze problems, build solutions, and create its own tools.

What I learned:

1. Headless-first tools enable AI autonomy — Godot’s CLI, GitHub Actions, and Docker made it possible for Claude to run the full development cycle without GUI intervention.

2. Claude Code builds tools for itself — Claude didn’t just write game code. It built development tools (visual editors, image processors) that it then used to work more effectively.

3. Personas as agents — A PM agent and target player persona helped Claude make autonomous decisions and evaluate its own work.

You can find the game here: https://gblab.itch.io/tidewater-cove

Note on AI Art: AI-generated content in games is controversial, and concerns about impact on artists are valid. This is a learning project focused on workflow and tooling. The AI-generated assets are placeholders to test the pipeline.

The Stack

A quick overview of how the project is set up:

• Godot 4.3 (headless) — Game engine with full CLI support—build, import, export without GUI

• Docker devcontainer — Reproducible environment with Godot, Python, Claude Code pre-installed

• Claude Code CLI — AI assistant with filesystem access, running inside the container

• GitHub CLI — Allows Claude to keep track of issues, create PRs and releases

• GitHub Actions — CI/CD pipeline: push to main → build → deploy to itch.io

• Python tools — Custom scripts for art generation, story editing, deployment

The key property: everything runs from the command line. No clicking, no GUI automation. Claude can execute the full workflow autonomously.

# The entire development cycle, scriptable
godot --headless --import              # Import assets
godot --headless --export-release ...  # Build for any platform
python3 tools/generate_character_sheet.py ...  # Generate art
gh pr create ...                       # Open pull request

The Devcontainer Setup

A Docker devcontainer makes this workflow possible. It provides a consistent, secure environment where Claude Code can operate with full autonomy.

What’s in the container: Godot 4.3 headless binary + export templates for all platforms, Python with image processing libraries (PIL), Claude Code CLI, Git and GitHub CLI

Why this matters:

1. Skip-permissions mode — Claude Code can run with --dangerously-skip-permissions inside the container. This means Claude can read files, write code, run builds, and execute scripts without asking permission for each action. The container itself is the security boundary.

2. Full autonomy — With skip-permissions enabled, Claude can execute multi-step workflows uninterrupted: generate art → import assets → build game → run tests.

Key Insight #1: Headless-First Tools Enable AI Autonomy

(game development in the command line - six terminal sessions)

If Claude can’t run it from the command line, Claude can’t use it autonomously.

Why Godot works well:

Godot’s workflow is scriptable from the CLI:

godot --headless --import                          # Import all assets
godot                                              # Run the game

This means Claude can:

• Generate art → import it → verify it appears correctly

• Make code changes → build → catch errors

• Run the full pipeline without human intervention

Other engines like Unity support headless builds, but require additional setup—command-line flags not exposed in the editor, virtual framebuffers on Linux, and workarounds for systems without graphics capabilities. Godot was designed CLI-first, which makes it simpler to automate.

I plan on doing a few more experiments with Godot — I think this aspect of Godot might just make it one of the strongest contenders if you are working with Claude Code for game development.

Key Insight #2: Claude Code Builds Tools for Itself

(visual node narrative editor)

Claude didn’t just write game code—it built development tools that it then used to work more effectively.

Tools Claude created:

• Visual Node Editor — Interactive HTML editor for story structure. Claude generates this to visualize branching narratives, then references it when making story changes.

• Character Sheet Generator — Generates expression grids, auto-crops to sprites. Claude runs this to create consistent character art, then imports the results.

• Screenshot Compositor — Composites game assets into promotional images. Claude creates marketing materials without launching the game.

The feedback loop: I describe a problem → Claude builds a tool to solve it → Claude uses that tool → Claude improves the tool when issues arise.

Example conversation:

Me: “It’s hard to see the story structure.”
Claude: builds visual node editor with drag-and-drop, undo/redo, auto-layout
Me: “Can you add the ability to see which nodes have choices?”
Claude: updates the tool, regenerates the visualization

Claude isn’t just a code generator. It’s a toolsmith that uses its own tools.

Custom tools — instead of researching which tool to buy or download, a custom one can be built for the specific need. This may impact the plugin ecosystem, particularly as tools increasingly need to be AI-accessible.

Key Insight #3: Personas as Agents

Beyond documentation, I created explicit personas that Claude could adopt or consult.

Morgan (PM Agent):

A product manager persona with explicit decision authority:

## PM Agent: Morgan

**Autonomous Authority:**
- Order and prioritize tasks
- Implement features within established guidelines
- Fix bugs without asking
- Make creative decisions that follow the art/story bibles

**Escalate to User:**
- Spending money (AI API costs)
- Major story changes
- Significant scope changes

**Never ask:** "Should I continue?" "What's next?" "Is this okay?"

This eliminated the friction of Claude asking permission for every small decision. Morgan checks the backlog, picks the next task, and executes.

Elena (Target Player Persona):

A detailed persona representing the target audience—a 29-year-old who reads cozy mysteries but has never played a visual novel. When testing, Claude can adopt Elena’s perspective:

“Play through Chapter 1 as Elena and provide feedback.”

Claude then evaluates pacing, identifies confusing moments, and flags anything that would alienate a visual novel newcomer. This provided useful feedback before involving real playtesters.

Domain Documentation as Experts:

The art bible, dialogue guide, and story bible serve as domain expertise. Claude consults these when making creative decisions—checking if a color palette matches the art bible, or if dialogue sounds right for a character’s voice.

What I Learned

The most surprising part was watching Claude build tools for itself. The visual node editor, the image processor—these emerged from conversations about problems, and then became part of Claude’s own toolkit.

The PM and player personas helped more than expected. Instead of asking “should I continue?”, Claude checks Morgan’s backlog. Instead of guessing what players want, Claude consults Elena’s preferences. Explicit decision authority reduced friction significantly.

I was also pleasantly surprised by how well Claude Code and Godot work together. I didn’t launch the editor once after initial setup. Godot’s CLI-first design made full autonomy possible. If you’re exploring AI-assisted game development, the combination is worth trying.