Project Configuration

AI ForgeKit uses two machine-local configuration files generated by /setup. Both files contain absolute paths specific to your machine and should not be committed to VCS.

project-config.json#

Location: Docs/_working/state/project-config.json

Generated by: /setup

Read by: /build, /map-codebase, /map-design, /state-save, /state-load, /health-check, and all agents when they need project-specific information.

Full schema#

{
  "project": {
    "name": "MyGame",
    "uproject_path": "/absolute/path/to/MyGame.uproject",
    "engine_root": "/absolute/path/to/UE_5.5",
    "engine_version": "5.5"
  },
  "vcs": {
    "type": "git",
    "default_branch": "main",
    "workspace": ""
  },
  "build": {
    "ubt_path": "/absolute/path/to/UnrealBuildTool.exe",
    "editor_cmd_path": "/absolute/path/to/UnrealEditor-Cmd.exe",
    "target": "MyGameEditor",
    "platform": "Win64",
    "configuration": "Development",
    "full_command": "\"<UBT_PATH>\" MyGameEditor Win64 Development \"-Project=<UPROJECT>\" -NoHotReloadFromIDE -progress"
  },
  "features": {
    "gas_enabled": true,
    "enhanced_input": true,
    "common_ui": false
  },
  "plugins": {
    "project_plugins": ["BlueprintAIAssistant"],
    "commandlets": []
  },
  "setup_completed": "2026-03-21T10:00:00Z",
  "setup_version": "1.0.0"
}

Fields#

project

• name: project name from the .uproject filename
• uproject_path: absolute path to the .uproject file
• engine_root: absolute path to the UE5 installation root
• engine_version: major.minor version string (e.g., 5.5)

vcs

• type: git, perforce, or none
• default_branch: default branch for Git (e.g., main or master)
• workspace: Perforce workspace name (empty for Git)

build

• ubt_path: absolute path to UnrealBuildTool.exe (Windows) or the UBT DLL path (Linux/macOS)
• editor_cmd_path: absolute path to UnrealEditor-Cmd.exe
• target: build target, typically <ProjectName>Editor
• platform: Win64, Mac, or Linux
• configuration: Development (default)
• full_command: the complete ready-to-run build command including all flags

features

• gas_enabled: whether the Gameplay Ability System was detected in source
• enhanced_input: whether Enhanced Input is enabled in the project
• common_ui: whether CommonUI is enabled

plugins

• project_plugins: list of project-specific plugin names detected in Plugins/
• commandlets: optional commandlet plugin configurations for Blueprint asset inspection (see below)

Commandlet plugin configuration#

If your project has a CLI commandlet that can export Blueprint CDO properties, configure it here:

{
  "plugins": {
    "commandlets": [
      {
        "name": "MyBlueprintTool",
        "run_name": "MyCommandlet",
        "invocation": "\"<ENGINE_CMD>\" \"<UPROJECT>\" -run=MyCommandlet -verb=<VERB>"
      }
    ]
  }
}

/map-design checks this field when gathering game design data. See Optional plugins for details on the asset reference chains this enables.

Manual editing#

project-config.json is valid JSON and can be edited directly. The most common manual edit is fixing the engine path after an engine upgrade or after moving the project to a different machine. Re-running /setup is usually easier.

---

settings.local.json#

Location: .claude/settings.local.json

Generated by: /setup

Purpose: Adds a permissions entry that allows Claude Code to run the build command for this specific project and UBT path.

Structure#

{
  "permissions": {
    "allow": [
      "Bash(\"<UBT_PATH>\" <Target> <Platform> Development \"-Project=<UPROJECT>\" *)"
    ]
  }
}

The allow entry is constructed from the paths discovered by /setup. Without this entry, Claude Code will ask for confirmation before running the build command (or refuse to run it, depending on your settings).

Merging with settings.json#

.claude/settings.local.json is merged with .claude/settings.json at runtime. The local file adds project-specific allow rules without modifying the shared settings.json that is committed to VCS.

---

VCS exclusion#

Both files contain absolute paths that are specific to your machine and must not be committed.

Git: add to .gitignore:

Docs/_working/state/project-config.json
.claude/settings.local.json

Perforce: add to .p4ignore or workspace view exclusion rules.

See Installation for the complete list of files to exclude from VCS.

---

Team setup#

Each team member runs /setup independently. The generated project-config.json and settings.local.json files are theirs alone. The rest of the AI ForgeKit files (CLAUDE.md, .claude/rules/, .claude/agents/, .claude/skills/, Docs/Design/, Docs/Dev/) are committed and shared so the entire team gets the same AI environment.