maxmsp-utils

Utility patches and tooling for Max/MSP and Max for Live, with an AI-agent-first development workflow.

Visualizer • Patch Evolution Policy • Contributing • License

---

Overview

This repository is a growing library of utility patches and supporting tools:

• Max patch/device assets (.maxpat, .amxd)
• agent-first patch query / edit tooling (maxpat_query.py, maxpat_ops.py)
• optional derived SQLite cache tooling (maxpat_cache.py)
• patch validation and policy enforcement scripts
• a lightweight read-only visualizer for inspecting patch topology

Repository Layout

Area	Purpose	Path
Patches	Canonical patch sources	patches/
Visualizer	Browser-based Max patch visualizer	tools/maxpat_visualizer/
Query + analysis tools	Patch graph/query utilities	tools/maxpat_query.py
Edit ops tool	Deterministic patch write ops	tools/maxpat_ops.py
Optional cache	SQLite FTS/RTree derived cache	tools/maxpat_cache.py
Validation tools	Policy + structural validation	tools/check_patch_policy.py, tools/validate_maxpat.py
Process docs	Patch evolution guardrails	docs/PATCH_EVOLUTION_POLICY.md

Agent-First Patch Workflow

For large patches, do not start by reading raw .maxpat JSON. Use the query/edit tools first:

1. python3 tools/maxpat_query.py --pretty describe (optional self-discovery for agents)
2. python3 tools/maxpat_query.py summary <patch>
3. python3 tools/maxpat_query.py find <patch> '<anchor>'
4. python3 tools/maxpat_query.py trace ... / neighborhood ... / region ... / nearest ...
5. python3 tools/maxpat_ops.py --pretty describe (inspect selectors/ops contract)
6. python3 tools/maxpat_ops.py validate-spec --ops <ops.json> [--contextual --file <patch>]
7. python3 tools/maxpat_ops.py apply <patch> --ops <ops.json> --dry-run
8. python3 tools/maxpat_ops.py apply <patch> --ops <ops.json>

Useful docs:

• tools/MAXPAT_QUERY_AGENT_USAGE.md
• tools/MAXPAT_OPS_AGENT_USAGE.md
• tools/MAXPAT_CACHE_AGENT_USAGE.md

Visualizer

A lightweight patch visualizer is available at tools/maxpat_visualizer/.

It supports:

• interactive patch browsing and subpatch drill-in
• search and object inspection
• optional semantic diff overlay (base vs target)
• directed route trace highlighting

Run locally:

python3 -m http.server 8765

Then open:

http://localhost:8765/tools/maxpat_visualizer/index.html

For full visualizer usage notes, see tools/maxpat_visualizer/README.md.

Patch Evolution Policy

Patch files (.maxpat / .amxd) are the source of truth in this repo. Scripted patch transforms are treated as one-time migrations only.

Policy details:

• docs/PATCH_EVOLUTION_POLICY.md

CI and Validation

CI enforces patch policy and structural validation through the Validate MaxMSP Patches workflow.

Checks run:

• python3 tools/check_patch_policy.py
• python3 tools/validate_maxpat.py

Run the same checks locally before pushing:

python3 tools/check_patch_policy.py
python3 tools/validate_maxpat.py $(find . \( -name '*.maxpat' -o -name '*.amxd' \) | sort)

Contributing

Contributions are welcome. See the full guide in CONTRIBUTING.md.

Quick checklist:

1. Create a worktree/branch for your change.
2. Treat patch files as canonical outputs.
3. Run local validation before opening a PR.
4. Include a concise summary and validation notes.

Current Limitations

There is no native test runner equivalent for Max patches in this repository. Full runtime E2E testing in CI is constrained by Max licensing and macOS/display requirements.

Until that setup exists, static policy and structural checks are the primary CI quality gate.

License

This project is licensed under the MIT License. See LICENSE for details.