maxforge

TEXT → PATCHER

Mass-produce Max patches.
Keep the source readable.

maxforge compiles a compact DSL into valid .maxpat files. Use loops, conditions, and arithmetic for the repetitive object creation that Max's visual editor handles poorly.

Read the docs Start with npx Versioned Max packages

Unofficial software. Not affiliated with, endorsed by, or sponsored by Cycling '74.

voice_bank.maxdsl COMPILES 
for i in 0..7 {
  osc_${i} = cycle~ ${110 + i * 27.5}
  amp_${i} = *~ 0.125
  osc_${i} -> amp_${i} -> dac

  if i < 4 {
    meter_${i} = meter~
    amp_${i} -> meter_${i}
  }
}
21objects
20connections
1source loop
FOR / IF / + − × ÷ 321 CATALOG ENTRIES AUTO LAYOUT SUBPATCHERS MAX ↔ DSL HTTP LIVE SYNC

00 / QUICKSTART

No global install.
One command to a patch.

Compile DSL to a Max patch
npx maxforge@latest compile input.maxdsl -o output.maxpat
Validate without writing
npx maxforge@latest validate input.maxdsl

01 / DSL

Describe intent.
Stop duplicating boxes.

Names become stable Max box IDs. Connections stay explicit. Layout can be automatic, pinned with at(x, y), or preserved as a full rectangle with at(x, y, width, height).

01

Generate at scale

Inclusive ranges, stepped loops, numeric conditions, and interpolated expressions create consistent banks without copy/paste drift.

for voice in 0..31 { ... }
02

Compile both ways

Build .maxpat from DSL, or decompile existing patch structure and positions back to editable text.

03

Nest cleanly

Define subpatchers inline, or register reusable abstractions and third-party externals with a strict project catalog.

04

Paste into Max

Emit compressed patch text for the clipboard when a file is unnecessary.

CLI reference →

02 / LIVE CONTROL

Let an agent read and replace
a managed patch scope.

A Max-owned service compiles desired DSL and sends ordered plans to one native maxforge object in each patch. The external inspects and mutates through the Max SDK—including text, comments, and bounded changed box/cord attributes—without a JavaScript bridge or screenshot. Project-scoped edit evidence can survive Max restarts without treating filenames or window titles as patch identity.

01 AI agent HTTP client
local authenticated HTTP
02 Max-owned service shared planner + state owner · Max's Node
local authenticated WS
03 maxforge native Max external

One object, no server setup

Install the Max package and create maxforge. Max's own Node runs the shared service; no separate runtime is shipped.

Max objectAUTO START
maxforge
Experimental means experimental.

Protocol v1 validates complete plans and reverse operations before mutation, then attempts managed-graph recovery after a failure. It is not transactional: inspect after every error before retrying.

03 / INSTALL

Choose the surface
you actually need.

CLI + LIBRARY

npm package

Use for offline compilation and the optional live HTTP client. Live service installation belongs to the Max package.

npm install maxforge
View on npm →
MACOS UNIVERSAL + WINDOWS X64

Max package

Use for native maxforge live inspection and mutation. Includes help, reference, docs, and examples.

Choose maxforge-vX.Y.Z.zip Versioned macOS release archives are Developer ID signed and notarized by CI.
AGENT WORKFLOWS

Skills

Install offline authoring or stricter live-control instructions for compatible coding agents.

npx skills add bbb-max-externals/maxforge
Inspect the skills →

SOURCE-CONTROL THE BORING PART

Write the pattern once.
Forge the patch.

Read the documentation Browse examples