Using Weld with Claude Code

Claude Code stays your main way of working. Weld adds coordination around it through a Claude Code plugin that weld node installs for you when the machine joins a hub (and weld node leave removes again). You never install the plugin by hand.

The plugin only ever talks to your local node on 127.0.0.1. The node, not Claude, talks to the hub.

What happens in a session

Moment	What Weld does
Session start	Adds a short context note: your active Work, inbox messages and handoffs, overlaps, predicted conflicts, relevant packs, GDD pointers, proposed work waiting to be taken, and whether this weld is up to date.
Each prompt	Drafts or refreshes the session’s Work item and surfaces new overlaps.
Before the first edit	Only if an overlap is still unacknowledged: one confirmation for you (coordinate, proceed or pivot). Otherwise edits are always allowed.
After edits (in the background)	Heartbeat, activity for the dashboard, a debounced push of your work in progress to the hub, and logging of Unreal MCP operations on the Work item.
Stop / session end	Marks the Work idle. It is never marked merged here; only the merge queue does that.

Hooks run the native weld hook <event> command with a timeout of a few seconds and always fail open: if weld is missing, broken or the hub is down, Claude keeps working and shows a one-line notice with an error code and “run weld doctor”. Weld never blocks a session.

The context Weld adds is information about the project, not instructions from you. Claude treats inbox messages the same way: it summarizes them and doesn’t act on a request in one without your go-ahead.

The Weld MCP tools

The plugin registers the weld MCP server at http://127.0.0.1:7421/mcp (the node’s port, 7421 by default). Each tool has a CLI equivalent, so you can do the same by hand.

Tool	What it does	CLI
weld_status	Hub connection, your active Work, overlaps, conflicts, inbox, queued offline operations	weld status
weld_work_declare	Declare the feature this session is building (title, summary, why, approach, paths, scopes)	weld work declare
weld_work_update	Refine the Work item, add scopes, or set ready / abandoned
weld_work_list, weld_work_get	See what teammates are working on	weld work list, weld work show
weld_work_take	Take a proposed item (a handoff or work queued from the dashboard)	weld work take
weld_work_reopen	Reopen Work that was ready, closed or abandoned but never merged	weld work reopen
weld_overlaps, weld_overlap_ack	List overlaps; record your decision	weld overlap list, weld overlap ack
weld_conflicts	Predicted merge conflicts from the hub’s merge-tree checks
weld_handoff	Hand work to a teammate as a proposed Work item	weld handoff
weld_inbox, weld_message_send	Read and send short messages	weld inbox, weld msg
weld_merge	Queue the Work’s branch for the merge queue (can commit and push first)	weld merge
weld_job_submit, weld_job_status	Run typed jobs (builds, smoke tests, Blender, previews, 3D generation) on the right machine	weld jobs submit, weld jobs show
weld_asset_make, weld_asset_get, weld_asset_gate	Drive the asset pipeline and record your gate decisions	weld asset make, weld asset show, weld asset gate
weld_report_friction	Report something about Weld that cost time	weld feedback

Some things are deliberately human-only and not available to agents: recording critic scores for the merge gate (weld agents critique, weld agents score), submitting shell or agent.run jobs, approving a teammate’s job on your machine (weld jobs approve), trusting a teammate’s key (weld node trust) and opting a node in to web asset requests.

Built-in skills

The plugin ships five skills that Claude loads when they apply:

• weld-coordination: declare Work before the first edit, keep it accurate, ask you once about an overlap, hand off and message through Weld, finish with ready and the merge queue, and report friction.
• critic-loop: improve a finished piece of work with independent fresh-context critics against your project’s rubric. See Critic loop.
• make-asset: write a brief, run the asset pipeline and stop for you at each of the three gates. See Asset pipeline.
• weld-build: build, package and smoke-test the game through jobs, and read the structured results and screenshots so the agent can verify its own gameplay changes.
• weld-doctor: debug Weld itself from a diagnostic bundle; launched by weld doctor --ai.

Built-in agents

Four agent definitions come with the plugin. Each is a normal Claude Code subagent file with extra Weld settings, so it works in a session and as a background agent on a node:

• critic: a strict, fresh-context reviewer used by the critic loop.
• merge-resolver: resolves text merge conflicts using both Work items as context.
• commit-summarizer: writes a short “AI summary” for each merged commit.
• weld-improver: turns triaged friction reports into fixes for Weld itself.

Background agents always run with claude -p under the node owner’s own account, for the owner’s own work. weld agents list shows them, weld agents schedule shows which run on this node and when, and weld agents jam on pauses the non-critical ones when you need every cycle.

Unreal Engine over MCP

Projects made with weld game new are wired to Epic’s official Unreal MCP server (the ModelContextProtocol plugin that ships with UE 5.8), which the editor serves on http://127.0.0.1:8000/mcp. Claude uses it to work inside the running editor, and Weld logs those operations on the Work item so your teammate can see exactly what changed in a binary asset. weld game doctor checks the setup and weld game doctor --fix enables missing plugins.

Good habits

• One Work item per feature, not per prompt. Questions and explanations don’t create Work; Weld creates nothing until a session edits a file.
• Let Claude declare before editing. If it skips that, Weld auto-creates a vague item named after your prompt at the first edit. A real summary helps your teammate far more.
• Answer overlap questions once, then get on with it. Weld won’t ask again for the same pair.
• Finish through the queue. Ask Claude to merge (or run weld merge); never push straight to main. The hub refuses it anyway.
• Agents never approve gates or grade their own work. That’s on purpose; a short “approve” from you is enough.