Installation

Prerequisites#

• Claude Code CLI: installed and authenticated (docs)
• Unreal Engine 5.0+: source build or Epic Games Launcher
• Git or Perforce for version control
• PowerShell (Windows, pre-installed) or bash (macOS/Linux, pre-installed)
• Optional: jq for enhanced /health-check validation on macOS/Linux

Step 1: Get AI ForgeKit#

Option A: Clone the repository

git clone https://github.com/sts-forge/unreal-dev-harness.git

Option B: Download ZIP

Download from the GitHub releases page and extract to a temporary location.

Step 2: Copy files into your project#

Copy these items into your Unreal project root (the directory containing your .uproject file):

CLAUDE.md
.claudeignore
.claude/          (entire directory)
Docs/             (entire directory)

Do not copy README.md, LICENSE, CHANGELOG.md, install.md, .gitignore, or .git/.

Step 3: VCS setup#

Add the following entries to keep ephemeral session state out of version control.

Git: add to .gitignore:

# AI ForgeKit ephemeral state
.claude/settings.local.json
Docs/_working/state/SESSION_CONTEXT.md
Docs/_working/state/SESSION_SNAPSHOT.json
Docs/_working/state/build-status.json
Docs/_working/state/project-config.json
Docs/_working/sessions/
Docs/_working/notes/
Docs/_working/retro/

Perforce: add the same patterns to your .p4ignore or workspace view, using ... instead of / for recursive exclusion:

.claude/settings.local.json
Docs/_working/state/SESSION_CONTEXT.md
Docs/_working/state/SESSION_SNAPSHOT.json
Docs/_working/state/build-status.json
Docs/_working/state/project-config.json
Docs/_working/sessions/...
Docs/_working/notes/...
Docs/_working/retro/...

The shared files (CLAUDE.md, .claude/rules/, .claude/agents/, .claude/skills/, Docs/Design/, Docs/Dev/) should be committed so the entire team gets the same AI environment.

Step 4: Run /setup#

Open Claude Code in your project directory:

cd /path/to/your/ue5project
claude

Then run the setup wizard:

/setup

The wizard auto-discovers your engine path, VCS type, GAS usage, and installed plugins. It generates project-config.json and settings.local.json with your machine-specific paths. See Setup for a full walkthrough of what /setup does.

Step 5: Populate the Dev wiki#

/map-codebase

This scans your Source/ directory for UCLASS, USTRUCT, and UENUM declarations, classifies them into systems, and writes the Dev wiki pages in Docs/Dev/. The AI uses these pages to understand your project's specific class hierarchy rather than guessing from generic UE5 knowledge.

Step 6: Verify#

/health-check

Runs structural and semantic validation and reports check IDs for any issues found. Most common issues are a missing directory or a settings.local.json syntax error.

Recommended first session#

Run these commands in order on first setup:

1. /setup: configure (this installs the official Anthropic plugins: skill-creator for custom skill development, clangd-lsp for C++ code intelligence, and pr-review-toolkit for PR reviews)
2. /map-codebase: scan C++ source
3. /map-design: discover game design content (interactive)
4. /health-check: verify everything is wired up
5. Describe a feature, report a bug, or ask a question

Team setup#

Each team member runs /setup independently. It generates machine-local project-config.json and settings.local.json that should not be shared. The wiki content and rule files are committed and shared.

Troubleshooting#

/setup can't find my engine#

Set the UE_ROOT environment variable to your engine root before opening Claude Code:

# macOS/Linux
export UE_ROOT="/path/to/UE_5.5"

# Windows PowerShell
$env:UE_ROOT = "C:\Program Files\Epic Games\UE_5.5"

Build command fails#

Check .claude/settings.local.json: the build permission must match your exact UBT path. Re-run /setup to regenerate it.

Perforce hook conflicts with Git#

The VCS hook auto-detects type. If detection is wrong, open Docs/_working/state/project-config.json and verify "vcs": { "type": "git" }.

/health-check reports failures#

Read the specific check IDs in the output (S1–S18 for structural checks, L1–L12 for logical checks) and fix the reported issues.