# Golem — AI Assistant for Godot 4.x

**v0.13.0**

Build Godot games with AI. Chat dock in the editor + MCP bridge for Claude Code. BYOK — your model, your key, no subscription.

<!-- TODO: add chat dock screenshot -->

## Features

- **Chat Dock** — Agent loop with streaming, tool calling, conversation persistence, right inside the Godot editor
- **26 Tools** — Scenes, scripts, screenshots, input simulation, project settings, node manipulation…
- **MCP Bridge** — Works with Claude Code, Cursor, Windsurf, Continue.dev, Cline via TCP
- **BYOK Multi-Provider** — OpenAI, OpenRouter, Ollama, Gemini, or any OpenAI-compatible endpoint
- **25 Expert Skills** — Slash commands for Claude Code (plan, build, debug, test, audit…)
- **7 Hooks** — Auto-lint, connection check, .tscn protection, context restore after compaction
- **Auto-Updates** — GitHub Releases check every 24h, one-click update in the editor

## Quick Start

### Chat Dock (recommended)

1. Install: `uvx golem-mcp install /path/to/your/godot-project`
2. Enable plugin: **Godot > Project Settings > Plugins > Golem MCP**
3. Open the **Golem** dock → enter your API key in Settings → chat

### MCP Bridge (Claude Code / Cursor / Windsurf)

1. Install: `uvx golem-mcp install /path/to/your/godot-project`
2. Enable plugin: **Godot > Project Settings > Plugins > Golem MCP**
3. Open your project in Claude Code → type `/godot`

## Installation

### Option 1 — CLI (recommended)

```bash
uvx golem-mcp install /path/to/your/godot-project
```

This copies the plugin, skills, hooks, and generates configs automatically.

Then enable the plugin in **Godot > Project Settings > Plugins > Golem MCP**.

### Option 2 — ZIP Installer

1. Download the latest `.zip` from releases
2. Extract and run `install.bat` (Windows) or `./install.sh` (macOS/Linux)
3. Enter your Godot project path
4. Enable the plugin in Godot

### CLI Options

```bash
# Choose your AI assistant
uvx golem-mcp install /path/to/project --agent cursor
uvx golem-mcp install /path/to/project --agent windsurf

# Force overwrite existing install
uvx golem-mcp install /path/to/project --force

# Use a local clone instead of uvx (for development)
uvx golem-mcp install /path/to/project --local /path/to/golem-mcp

# Skip skills installation
uvx golem-mcp install /path/to/project --skip-skills
```

### Manual installation

<details>
<summary>If you prefer to install manually</summary>

#### 1. Plugin Godot

Copier le dossier `godot-plugin/` dans ton projet Godot :

```
ton-projet/addons/golem-mcp/ ← contenu de godot-plugin/
```

Activer le plugin : **Project > Project Settings > Plugins > Golem MCP**

#### 2. Serveur MCP Python

```bash
cd golem-mcp
uv sync
```

#### 3. Configuration Claude Code

Créer un `.mcp.json` à la racine de ton projet Godot :

```json
{
  "mcpServers": {
    "godot": {
      "type": "stdio",
      "command": "uvx",
      "args": ["golem-mcp"]
    }
  }
}
```

</details>

### Auto-updates

The plugin checks for updates every 24h via GitHub Releases. When a new version is available, you'll get a dialog in the Godot editor to update in one click.

## Tools (26)

Available in both the Chat Dock (tool calling) and MCP Bridge (Claude Code tools).

| Tool | Description |
|------|-------------|
| `godot_get_scene_tree` | Scene tree hierarchy (`detail_level`: full/summary) |
| `godot_inspect_node` | Node properties, signals, groups (`detail_level`: full/summary) |
| `godot_get_editor_screenshot` | Editor viewport capture |
| `godot_get_game_screenshot` | Running game capture |
| `godot_play_scene` | Run a scene |
| `godot_stop_scene` | Stop the running scene |
| `godot_get_errors` | Retrieve errors |
| `godot_clear_logs` | Clear logs |
| `godot_execute_script` | Run GDScript in the editor |
| `godot_view_script` | Read a script |
| `godot_add_node` | Create a node |
| `godot_delete_node` | Delete a node |
| `godot_update_property` | Modify a node property |
| `godot_move_node` | Move a node in the tree |
| `godot_duplicate_node` | Duplicate a node |
| `godot_get_input_map` | Read input actions |
| `godot_project_settings` | Read/write project settings |
| `godot_project_context` | Full project dump (settings, autoloads, input map, files) |
| `godot_save_scene` | Save the current scene |
| `godot_write_script` | Write a .gd file |
| `godot_attach_script` | Attach a script to a node |
| `godot_get_logs` | Game + engine logs (incremental) |
| `godot_create_scene` | Create a new scene |
| `godot_open_scene` | Open an existing scene |
| `godot_add_nodes` | Batch: create a full node hierarchy |
| `godot_find_nodes` | Search nodes by type, group, name, script |
| `godot_simulate_input` | Simulate input sequences in the running game |

## Skills (25, MCP Bridge only)

Slash commands for Claude Code / Cursor / Windsurf. The Chat Dock uses tools directly with dynamic system prompts.

### Workflow Commands

| Skill | Role |
|-------|------|
| `/init` | Bootstrap a new project (vision → deliverables → structure) |
| `/golem-dev` | Switch context to work on Golem MCP itself |
| `/deliverable <name>` | Focus on a specific deliverable until completion |
| `/checkpoint` | Snapshot project state into CHECKPOINT.md |
| `/references` | Extract reusable patterns from the project |

### Planning & Simulation

| Skill | Role |
|-------|------|
| `/godot` | Router — dispatches to the right skill based on intent |
| `/godot-plan` | Plan a feature — interrogate, structure, produce a mini-PRD |
| `/godot-sequence` | Define game flow as YAML (loops, states, emotional arc) |
| `/godot-simulate` | Paper-prototype a sequence (friction, balance, edge cases) |
| `/godot-gate` | Validate readiness before construction (auto-checks + questions) |

### Construction

| Skill | Role |
|-------|------|
| `/godot-architecture` | Design modular architecture (EventBus, components, scripts) |
| `/godot-scene` | Build a Godot scene via MCP tools |
| `/godot-composition` | Structure UI (tokens, containers, layout, torture tests) |
| `/godot-theme` | Create a design token system via Theme resource |
| `/godot-behavior` | Add states, transitions, tweens and feedback loops to UI |

### Game Feel, VFX & Audio

| Skill | Role |
|-------|------|
| `/godot-juice` | Add game feel (screenshake, freeze, squash, hit effects) |
| `/godot-vfx` | Create visual effects (particles, shaders, lighting) |
| `/godot-audio` | Set up audio (bus, music manager, SFX pool, spatial) |
| `/godot-save` | Implement save/load (settings, game state, slots, migration) |
| `/godot-camera` | Configure 2D camera (follow, zoom, limits, cinematic) |

### Debug & Audit

| Skill | Role |
|-------|------|
| `/godot-debug` | Diagnose and fix issues step by step |
| `/godot-test` | Automated tests (input simulation + logs + verification) |
| `/godot-design-audit` | Audit UX via screenshots and produce a report |
| `/godot-status` | Scan project state, generate DEVLOG, track progress |

## Hooks

7 Claude Code hooks in `hooks/` (Python, cross-platform):

| Hook | Event | Role |
|------|-------|------|
| `check_connection.py` | PreToolUse (godot_*) | Checks TCP connection before each MCP call |
| `block_tscn_edit.py` | PreToolUse (Edit/Write) | Blocks direct .tscn file editing |
| `pre_compact.py` | PreCompact | Saves project state before context compaction |
| `gdscript_lint.py` | PostToolUse (godot_write_script) | Lints GDScript after writing (+ `:=` Variant detection) |
| `copy_skills.py` | PostToolUse (Edit/Write) | Auto-copies modified skills to test project (dev) |
| `check_project_sync.py` | PostToolUse (Edit/Write) | Syncs deliverables, checkpoint, references |
| `compact_context.py` | SessionStart (compact) | Restores project context after compaction |

### Installation in your Godot project

Copy the template and adjust paths:

```bash
cp hooks/settings.example.json your-project/.claude/settings.json
# Edit paths in the file
```

Or add manually in `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__godot__.*",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/check_connection.py", "timeout": 3}]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/block_tscn_edit.py", "timeout": 3}]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/compact_context.py", "timeout": 5}]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/pre_compact.py", "timeout": 5}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "mcp__godot__godot_write_script",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/gdscript_lint.py", "timeout": 5}]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/check_project_sync.py", "timeout": 3}]
      }
    ]
  }
}
```

## Workflow

### New project (full)
```
/init → /deliverable <first> → /checkpoint → /deliverable <next> → ...
```

1. **`/init`** — Full bootstrap: vision, gameplay loop, vertical slice, deliverables, structure
2. **`/deliverable <name>`** — Implement ONE deliverable until completion
3. **`/checkpoint`** — Snapshot state, validate progress
4. Repeat until vertical slice is complete

### Resuming a project
```
/init (detects state) → /checkpoint → /deliverable <in_progress>
```
`/init` auto-detects existing files and offers to resume.

### Working on Golem MCP itself
```
/golem-dev
```
Switches context to modify the MCP itself. Return with `/init` or any Godot skill.

### Classic workflow (no deliverables)
```
/godot-plan → /godot-sequence → /godot-simulate → /godot-gate → /godot-architecture → /godot-scene
```

1. **`/godot-plan`** — Define the vision, mechanics, target feeling. Produces `GAME_PLAN.md`
2. **`/godot-sequence`** — Formalize game flow as YAML (loops, states, data)
3. **`/godot-simulate`** — Test the game on paper (3 modes: narrative, balance, exhaustive)
4. **`/godot-gate`** — Validate everything is ready before coding
5. **`/godot-architecture`** — Scaffold Core (EventBus, GameState), folder structure
6. **`/godot-scene`** — Build scenes one by one following the plan

### Building UI
```
/godot-composition  →  /godot-theme  →  /godot-behavior
```
**Structure** (containers, tokens, roles) BEFORE **theme** BEFORE **behavior** (animations, states).

### Debug
```
/godot-debug  →  fix  →  /godot-status
```
Direct route — no prerequisites.

### Quick prototyping
```
/godot-scene  (QUICK mode, no plan or architecture)
```
For testing an idea fast. Transition to full flow if the prototype works.

## Troubleshooting

### "Connection refused" / Port unavailable

**Symptom**: The `check_connection.py` hook blocks with "Godot is not connected"

**Possible causes**:
1. Godot is not open
2. The Golem MCP plugin is not enabled
3. Another process is using port 3571

**Solutions**:
```bash
# Check if port is in use
lsof -i :3571        # macOS/Linux
netstat -ano | findstr :3571  # Windows

# Change port (if conflict)
export GOLEM_PORT=3572  # Before launching Claude Code
```

In Godot: **Project > Project Settings > Plugins > Golem MCP** must be enabled (checkbox checked).

### "No scene is currently running" (screenshot)

**Symptom**: `godot_get_game_screenshot` returns an error

**Cause**: The game is not running, or the scene crashed

**Solution**: Run the game with `godot_play_scene` before capturing

### Empty screenshot / base64 error

**Symptom**: "Screenshot file was empty or corrupted" or API error "image cannot be empty"

**Possible causes**:
1. `GolemCapture` autoload not injected in the game
2. The game crashed before capture
3. Race condition (capture too fast)

**Solutions**:
1. Check that `golem_capture.gd` is copied in `addons/golem-mcp/`
2. The system retries automatically 3 times — if it still fails, check Godot logs
3. Use `godot_get_errors` to see if the game crashed

### Lint warnings after godot_write_script

**Symptom**: The `gdscript_lint.py` hook reports warnings

**This is normal** — lint is a safety net. Common warnings:
- `Missing 'extends'` — add `extends Node` (or the correct type)
- `print() found` — replace with `GolemCapture.game_log()` to see logs via MCP
- `await inside _process` — forbidden in @tool, use a deferred pattern
- `Camera2D position modified` — use `offset` instead of `position` for screenshake
- `':=' with Variant source` — replace `:=` with `: Type =` when source is Array, Dict, ternary, `.duplicate()`

### Ghost connections in Godot logs

**Symptom**: "Condition '!is_open()' is true" repeated in logs

**Cause**: Ghost TCP connections (port probes)

**Solution**: Fixed in v0.5.1 — the server silently ignores these connections. Update the plugin.

## TCP Protocol

JSON lines on port 3571 (configurable via `GOLEM_PORT`).

**Request:** `{"id": "uuid", "tool": "get_scene_tree", "args": {}}\n`

**Response:** `{"id": "uuid", "ok": true, "result": "...", "type": "text"}\n`

## License

MIT
