ValAgentBridge

ValAgentBridge was made to help with modding Valheim: it lets an AI agent automate and monitor the testing of mods. Instead of launching the game, loading a world and checking things by hand after every change, you ask the agent (Claude Code, through the GABS MCP server) and it does it in the running game.

For mod developers. Needs GABS (not on Thunderstore) and an AI agent such as Claude Code. Setup, the full tool list and test scripts: GitHub.

Best with ValPerfMonitor

ValAgentBridge pairs well with ValPerfMonitor, which measures what each installed mod and each part of Valheim costs: CPU time, memory allocations, load times and network. With both in the same profile, the monitor adds its own perf/* tools to the bridge, so an agent can run a whole performance measurement without anyone at the keyboard: get into the world, run the monitor's test suite or a live A/B test of a change, and read the results. Optional: the bridge works on its own.

Features

• Game: enter a world in one call, create characters and worlds, load, save, log out
• Movement: walk, pathfind, jump, look, teleport
• Player actions: attack, block, interact, open a station, chest, portal or door by its ID without aiming, pick up, drop, equip, eat, craft, repair, build, press keys, mouse wheel and drag (map zoom and pan), click menus
• Console commands: any game or mod command, with its output
• Test setup: give items, spawn creatures, spawn any object (boats on the water, never on top of another ship), clear enemies (once or for the whole session), time, weather, health, god/ghost mode, game speed, mod settings, live values
• Lookups: player state, inventory and backpacks, nearby objects, locations, items and recipes
• Monitoring: screenshots, log, on-screen messages, player events
• Live inspection: browse and search every object in the game (world, menus, HUD, mod objects), read and change live values, switch objects on or off, watch method calls
• Test scripts: JSON steps and checks with pass/fail reports; optional steps, repeats, short summaries
• Stuck detection: no frames, waiting popups, stalled loads
• Other mods: list mods and settings, use commands they add

Cheat console commands run only with allowCheats or when devcommands is already on.

The agent doesn't take the character away from you: moving, turning and teleporting are refused while you steer a ship, sit, have a menu open or used keyboard or mouse in the last few seconds, unless the agent asks and forces it.

Clearing hostile creatures is off by default. When testing starts the agent offers to turn it on, so a creature can't kill the character mid-test; say no if you are testing creatures.

What you need

• Claude Code (or another MCP client)
• GABS 1.1 or newer (download from its releases page), which starts the game and connects the agent to ValAgentBridge

Started without GABS, ValAgentBridge does nothing: no patches, no listener, no per-frame work.

Setup

1. Install ValAgentBridge in a profile with your mod manager.
2. Register GABS as an MCP server: claude mcp add --scope user gabs -- <path>\gabs.exe server.
3. GABS game config, %USERPROFILE%\.gabs\config.json: a game valheim that starts valheim.exe with --doorstop-enabled true --doorstop-target-assembly <profile>\BepInEx\core\BepInEx.Preloader.dll.
4. Ask the agent to start Valheim (games_start valheim), then world/enter to load into a world. It finds every tool and its arguments itself.

The full tool list is also in TOOLS.md in this package.