The problem with "a route that works"
Ask a router for a way around a beam and it will find one. Ask it again with a slightly different start and it finds another. Both clear the clash, both pass a clash test, and one of them is the fix a senior coordinator would draw while the other is the fix that gets marked up at the next coordination meeting.
The difference is rarely geometry. It is the second elbow nobody needed, the drop out of the trade's height zone, the dip that leaves a pressurised pipe with a low point to drain, the new hole in a fire-rated wall. Those are judgement calls, and an AI asked to "fix the clash" makes them differently each time unless something holds them still.
ClashFree holds them still with a scorer. Core code lists the options and prices them from data; the AI chooses and explains. Neither does the other's job.
Step 1: list every feasible option
For the run that gives way (see why the pipe moves, not the duct), ClashFree builds the list from the free space around the clash and from the run itself, not from a prompt:
- Offsets up, down, left and right where there is room, at the smallest distance that clears the clash (with the clash test's clearance) and at the profile's preferred distance, with 45° and 90° fittings.
- Drag: move the straight with its end fittings the way a modeller drags it in Revit, stretching the neighbours that run along the move or adding a transition. A jog the move makes redundant is removed.
- Shift and stretch where the run ends in a dead end, tilt tee where it is the branch of a tee (the tee turns, one elbow), and slide tee where it tees off a main.
- Move the whole run when it is short enough to shift as a piece.
- The router's best reroute on each side, following the run through its bends.
Each option gets an id (o1, o2…), its parameters, its score with every term, the hard limits it passed, and the bill of what it changes. The pane's AI proposes the offsets and whole-run moves itself; drags, tee moves, shift and stretch and reroutes are carried out when Claude drives ClashFree over MCP, and when one of them scores best the pane's AI flags the clash and names it. Update 2026-10-25: the pane's AI now carries out all of these verbs itself, from the same options and checks as Claude over MCP.
Step 2: hard limits remove options before any score
A hard limit is not a large penalty. It is a gate. An option that crosses a project's ceiling line, cuts a structural wall or beam, moves gravity drainage, lifts a condensate line off its fall or leaves a riser's slab opening is removed before scoring, and it stays visible with the limit that removed it. The same validator checks the AI's own parameters, so an override cannot reintroduce what the gate removed. The full list is in Hard limits the AI cannot break.
Step 3: the terms of the score
What survives is scored. Lower is better. Every term is a base weight that a project or user profile may tune, multiplied by the class factors of the run being changed:
| Term | Base weight | What it prices |
|---|---|---|
| fittings | 300 each | Every added elbow or transition. × 2 on air ducts, 2.5 on sprinkler, smoke-extract and kitchen-exhaust, 1.5 on cable tray, 0.5 on conduit. |
| length | 1 per mm | Material added to the run; a fix that saves length scores nothing here. |
| move | 0.25 per mm | How far the run moves from where it was designed. |
| leave_zone | 1 per mm | Each millimetre outside the trade's height zone, when the project defines one. |
| walls | 5,000 each | A new crossing of a non-structural wall, plus more when it is fire-rated (a damper or a firestop). |
| low_high | 1,000 each | A low or high point a drag adds away from the obstacle: a dip that climbs back where nothing needs it. |
| verb | 0.5 per mm | Moving a whole run: the length of run you move. |
| class | class factors | A reroute's fittings and added length at its class's cost, since the router prices them at base. |
| precedent | −800 | A bonus when the option sits where neighbour runs of the same system and size already pass, within 50 mm. |
The weights encode ordinary practice: an elbow is worth about 300 mm of pipe, a new wall opening is a last resort, and a dip that leaves a pressurised pipe needing a drain valve is worse than an extra pair of fittings.
A worked example
A DN80 heating pipe runs through a concrete beam in a corridor. The beam is in the linked structural model, so the pipe moves. Above the beam there is no room: it meets the slab. A structural wall stands 380 mm to the east. The project's coordination profile sets a ceiling line at 2700 mm. Three DN80 heating pipes nearby already pass under the same beam, 250 mm below the pipe's level.
| Option | move | fittings | length | other | score |
|---|---|---|---|---|---|
| o1 Offset down 250 mm, 45° | 62.5 | 600 | 207 | precedent −800 | 70 |
| o2 Drag the straight 250 mm down | 62.5 | 0 | 0 | low_high 1,000, precedent −800 | 263 |
| o3 Offset down 250 mm, 90° | 62.5 | 600 | 500 | precedent −800 | 363 |
| o4 Offset left 400 mm, 45° | 100 | 600 | 331 | — | 1,031 |
| o5 Reroute on the west side | 150 | 1,200 | 900 | walls 5,000 | 7,250 |
| Offset up over the beam | no room: the beam meets the slab | removed | |||
| Offset right 400 mm | structural wall 380 mm east (hard) | removed | |||
| Offset down 450 mm | below the ceiling line 2700 (project) | removed | |||
Three things decide this one. The drop the neighbours already use earns the precedent bonus, so the down options lead. Between the two ways of dropping, 45° fittings add 207 mm of pipe against 500 mm for 90°. And the drag, which adds no fittings at all, loses because it leaves a dip on either side of the beam: a heating pipe with two new low points away from the obstacle is an unfinished fix, and low_high says so. The reroute is feasible and absurd, which the wall term makes plain.
Step 4: the AI chooses, and has to explain
The AI receives the list, the terms, the removed options and their reasons, the coordination profile with the source of each value, and the run context. It picks an option by id; the default is best. Its explanation cites what decided: "kept the 2700 ceiling line (project); matched the neighbours' level under the beam; 45° fittings save 293 mm of pipe".
The AI reads what the table cannot: a system name or comment that marks a run as temporary, the use of a room, how the next corridor was laid out. When that evidence says the scored order is wrong here, it may propose its own strategy and parameters, but only with an override_reason, which is logged and shown to you beside the proposal. It cannot propose what the validator removed.
With option: best, ClashFree verifies options in score order: it applies the fix inside a Revit transaction group, checks it, rolls it back, and falls back to the next option when a check fails, at most three tries, counted as one failed fix if all three fail. You see the first one that passed, with its score, its runners-up and its bill.
Step 5: Revit has the last word
A score is an estimate from free-space boxes and the run's shape; Revit has the real model. Each candidate is applied and checked for the things a score cannot promise: the clash is gone with the clash test's clearance kept, every joint reconnected, no new clash against the host model or the loaded links. Only then is it rolled back and offered to you as a preview, and only your Keep commits it.
Tuning the weights for your office
The base weights are general practice. A project file can change the soft weights, for example to make leaving the height zone more expensive on a tight ceiling. Your own preferences can change soft weights only; hard limits come from the base and the project, so a preference never loosens a ceiling line.
ClashFree also learns what you keep, carefully. Each Keep and Reject is logged locally with the chosen option, its runners-up and their scores. When you keep the second-ranked option for the same reason three times on one project, the pane suggests a preference, with the evidence. It never promotes one by itself.
Next: the limits behind step 2, in Hard limits the AI cannot break, or see the scorer on your own model in the free beta.