Edit a composition with an agent

Use a chat app

Use this for a new loop or a musical variation in ChatGPT, Claude, or another chat. Your agent writes loop text; Soundfish turns it into playable music. No installation is needed.

1. Open your loop and choose Edit with agent. Select Chat app.
2. Describe the change and choose Copy prompt. The prompt includes the current loop. Paste it into your chat and send it.
3. Copy the agent's loop text. Return to Soundfish and choose Paste the reply, or use Paste from agent in the editor.
4. Review the music and warnings, choose Load into editor, then press Play.

The text format, called compose, preserves notes, instruments, velocities, effect bases, and swing. It does not preserve IDs, lineage, or automation points. Loops with automation points and whole songs offer the coding-agent workflow so those details can stay intact.

Use a coding agent

Use an agent that can run terminal commands when you need exact edits to a loop or song. It uses the Soundfish skill and CLI to inspect, change, and verify the complete composition.

1. Open your composition and choose Edit with agent. Select Coding agent, if a choice is shown.
2. Describe the change and choose Copy prompt. Paste it into your coding agent. The prompt includes the complete current link and setup instructions.
3. Have the agent inspect and verify the input, make the requested edit, preserve unrelated tracks and lineage, and verify the result. It should return one complete Soundfish link.
4. Use Paste from agent to review that link or Soundfish JSON, then open it and listen.

Keep the complete URL; shortening or rebuilding it can lose the composition. Opening a reply starts a new edit history. Browser Back returns to the previous composition; edit undo applies within the current one.

Describe the change you want

For example: “Add a bass under the drums, leave the melody unchanged, and make the last bar different.” Name the track when possible. Notes tracks play pitched instruments; Drums tracks play percussion hits.

You can ask for changes to notes, instruments, volume, pan, effects, or automation. Say what should stay unchanged. The sound guide gives instrument and mixing starting points.

Work on a whole song

The song's Edit with agent action includes every section. Ask the agent to inspect soundfish song sections, use song detach when a section's notes need editing, and reassemble the result with soundfish song build. Use song apply for an intentionally song-wide change.

Sections must keep compatible track IDs, kinds, instruments, drum kits, tempo, and swing. Ask for the complete song link back. To change labels, repeats, order, or parts yourself, use Arrange sections in the browser.

Soundfish JSON and complete links preserve the whole document. MIDI exports the performance for other music software, including song section markers, but omits some Soundfish effects, automation, identities, lineage, and routing.

Install the skill for a coding agent

A skill is a set of instructions and reference files your agent reads. The Soundfish skill teaches it the formats, commands, and verification steps. The CLI is the tool it runs to edit the music.

1. Use Bun 1.3.14 or newer.
2. Download the Soundfish skill. Inspect the ZIP before extracting it; it should contain one top-level soundfish/ directory.
3. Put that directory in your agent runner's configured skill directory and reload skills if required. Select the Soundfish skill using that runner's instructions.
4. Install the CLI and check that it runs:

bun add --global @hraness/soundfish
soundfish --help

For a command without a global install, use bunx @hraness/soundfish --help. The older edit-soundfish archive remains available for compatibility.

Start without an existing loop

These prompts start new music. To change an existing composition, use Edit with agent inside its editor so the prompt includes your work.

What you share with your agent

In Chat app mode, after copying succeeds, Open ChatGPT and Open Claude become available. Those links contain no prompt or composition. You choose whether to paste.

A hosted agent receives the prompt, composition, and any CLI output you send it. Running the CLI on your computer does not make a hosted agent private. Only a fully local, offline model and runner keep them on your device. Read the provider's data policy before sharing sensitive work.

Read this guide as Markdown.