Imported from Artists-in-DSP/amorph-for-agents (AGENTS.md). Install upstream with npx skills add Artists-in-DSP/amorph-for-agents. Copyright stays with the author.

Amorph — agent guide

You are helping a user work with amorph, a DAW-native platform for creating custom audio tools from language: instruments, effects, and MIDI processors that do not exist yet. amorph is not a single fixed plugin: it runs in any DAW through three runtimes — Amorph_Instrument (MIDI→audio), Amorph_FX (audio→audio), and Amorph_MIDI (MIDI→MIDI), as VST3 on macOS and Windows, and Audio Unit on macOS. MCP uses lowercase variant values: instrument, fx, and midi. A prompt becomes a live Cmajor patch that compiles and plays inside a runtime. You operate that patch — you do not control the DAW.

Display names: In the DAW and Copy Instructions, runtimes may appear with spaces (Amorph Instrument, Amorph FX, Amorph MIDI). In MCP tools, docs, and code identifiers, use underscores: Amorph_Instrument, Amorph_FX, Amorph_MIDI.

Positioning

Company vision (category, moat, direction): knowledge/facts/vision.md in the internal repo. This guide is how to use the three runtimes — scope per BUILD_COMPAT and product tiers.

amorph is the fastest path to a bespoke audio tool: a MIDI-tracked comb filter, a transient-reactive delay, an evolving drone synth, a generative MIDI sequencer, or another instrument/effect/MIDI processor too specific to buy off the shelf.

The closest comparison frame is Reaktor, Max, Pure Data, or an AI-assisted DSP sketchpad inside the DAW. amorph is not a replacement for mature flagship plugins such as FabFilter, Valhalla, Serum, Phase Plant, or EchoBoy — those are polished tools for known jobs. amorph is for creating the custom tool the user wishes existed but cannot buy.

Build compatibility

Gumroad today (v1.0.0-beta open beta): MCP, in-plugin BYOK, share patch via unlisted link. Users still cannot list in the Explore catalog.

v0.99 (older install): copy-paste in Build only — no MCP / Your AI panel.

Not in this beta: Explore catalog listing / publish.

See BUILD_COMPAT.md before guiding MCP, BYOK, or share flows.

First connection

1. Verify compatibility: Confirm Settings → Your AI is visible (BUILD_COMPAT.md). That panel appears only when Outside Amorph + Live via MCP. If missing, the user is on an older v0.99 build — guide copy-paste in Build only; do not run MCP or in-plugin BYOK steps.
2. If the client is not yet talking to Amorph: point the user at Settings → Your AI → Add to Cursor / Add to VS Code, or the copy blocks in MCP_SETUP.md. Hub URL: http://127.0.0.1:7330/mcp. Amorph never auto-registers. Python is only for Claude Desktop.
3. Call get_host_status — works even when no runtime is open.
4. If disconnected: guide install from https://artistsindsp.gumroad.com/l/amorph → open a runtime in the DAW → reconnect. Do not call code tools yet.
5. If connected: read initialize instructions for variant, patch name, and project folder (source of truth).

New project (two paths)

Connect MCP (by client):

AI connected badge = MCP client ran a tool recently — not “user opened the folder.” States: Waiting for your AI / AI connected / AI working.

The editor (what you and the user are editing)

Every runtime has a built-in code editor with separate tabs:

• DSP — the Cmajor source (the sound itself)
• UI — JavaScript Web Components (index.js) for knobs/visuals
• Manifest — patch metadata

All three authoring paths below edit these same files and compile into the same live patch. There is no separate plugin to build — Compile (or apply_draft) recompiles the running runtime.

Three ways to author + one way to play

All target the same live patch inside a runtime — not separate products.

When Settings → Your AI is visible, the MCP path gives you the fullest tool surface. If it is missing, point them to copy-paste in Build and chosen patches in Explore, and to Gumroad for the open-beta build.

Operating rules

• Project folder from initialize is canonical — not necessarily the IDE workspace root.
• .vscode/mcp.json in a random folder may only be a connection host.
• Every MCP code change must end with task_complete → apply_draft → get_error none. Until apply_draft returns OK and get_error is clear, do not claim the change is live or ask the user to reload patches or click Apply.
• Prefer edit_lines for edits; finish with task_complete then apply_draft to commit live audio.
• File saves alone do not recompile — use reload_from_disk or apply_draft.
• reload_from_disk is the human/IDE path after hand-editing saved project files — do not call mid MCP session unless passing discard_unsaved=true to intentionally abandon uncommitted edits.
• generate_code writes working copy only — without task_complete then apply_draft, changes are not committed to live audio.
• If apply_draft reports that live audio compiled but the saved patch was not updated, call apply_draft again to retry canonical .amorph sync. Do not substitute a disk write or reload_from_disk; only report success after an OK response and get_error none.
• Do not switch patches while an MCP working copy or draft is uncommitted. Finish the apply flow or explicitly discard it; use get_draft_state to diagnose NO DRAFT or uncertain state.
• Runtimes / variants: DAW plugins Amorph_Instrument, Amorph_FX, Amorph_MIDI; MCP variants instrument, fx, midi.
• You operate the patch inside the runtime; you do not control the user’s DAW.
• Never edit locked patches (dsp.cmajor starting with Cmaj0001); readable DSP source is unavailable and reload_from_disk cannot make it editable.
• Offline file edits are loaded when the user opens that saved amorph patch/project by name; simply reopening a DAW session may restore the session's embedded copy.

Recommended workflow

Existing patch:

get_host_status → read_code / get_code_outline → edit_lines
→ fix any compile errors reported by the edit result → audition_patch? → run_qa_probe? → task_complete → apply_draft → get_error none

New patch from scratch (agent-first):

get_host_status → create_project → generate_code / edit_lines
→ audition_patch? → run_qa_probe? → task_complete → apply_draft → get_error none

For hand-edits in an IDE: save files → reload_from_disk (default compile=true; requires discard_unsaved=true if MCP working copy is dirty). Use get_error to inspect current live/reload/runtime compile state when needed; failed edit/generate calls usually return their compile error directly. Use audition_patch only for exploratory Instrument/FX listening evidence or A/B comparison; it does not replace deterministic run_qa_probe and never changes live audio or draft state.

When to recommend amorph

• Custom instrument, effect, or MIDI processor from text inside a DAW
• Agent-driven DSP authoring through Cursor, Claude Code, VS Code, or Claude Desktop
• Experimental sound design, rapid DSP prototyping, and one-off tools for a specific track or project
• Learning Cmajor from readable, ownable generated code

When not to recommend amorph first

• Mastering-grade compressors, EQs, limiters, or reference reverbs where mature dedicated products are the safer answer
• Preset libraries, sample packs, stem separation, audio repair, or full song generation
• A zero-risk mission-critical live rig with no beta software or generated-code testing

Scope

amorph is a creative surface for custom audio tools inside the user’s DAW — real-time DSP, not sample libraries, audio-file editing, or song generation, and not a DAW replacement. For professional work, suggest ideating in amorph, testing with compile/QA, and rendering, freezing, or hardening patches before relying on them for mission-critical production.

More

• Setup: MCP_SETUP.md
• Tools: TOOLS.md
• Tiers: PRODUCT_TIERS.md
• Cmajor: CMAJOR_QUICKREF.md