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 Max package

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 MCP 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).

Generate at scale

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

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

Compile both ways

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

Nest cleanly

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

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.

The MCP server compiles desired DSL and sends ordered plans to one native maxforge.sync 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 MCP restarts without treating filenames or window titles as patch identity.

01 AI agent MCP client

stdio

02 maxforge-mcp Node.js planner

local / token LAN WS

03 maxforge.sync native Max external

MCP configuration

Run the published server directly with npx. Node.js 20 or newer is required.

mcp.jsonJSON

{
  "mcpServers": {
    "maxforge": {
      "command": "npx",
      "args": [
        "-y",
        "--package=maxforge@latest",
        "maxforge-mcp"
      ]
    }
  }
}

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 + MCP

npm package

Use for DSL compilation, decompilation, planning, and the MCP server.

npm install maxforge

View on npm →

MACOS UNIVERSAL + WINDOWS X64

Max package

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

Download maxforge.zip macOS builds are ad-hoc signed and not notarized.

AGENT WORKFLOWS

Skills

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

npx skills add 2bbb/maxforge

Inspect the skills →

SOURCE-CONTROL THE BORING PART

Write the pattern once.
Forge the patch.

Read the documentation Browse examples

Mass-produce Max patches.Keep the source readable.

No global install.One command to a patch.

Describe intent.Stop duplicating boxes.