Guide / Working with an agent (optional)

Working with an agent (optional)

Fledgetone has no AI built in, no account and no keys. If you already use an agent that can use MCP tools, you can let it read your song and suggest changes: notes, clips, levels, effects, automation, tempo and markers. You hear every suggestion before and after, then accept it or not. The agent never changes your song itself, and nothing is accepted for you. It's entirely optional: nothing about it runs until you ask.

Fledgetone sends nothing anywhere. Your agent sends what it reads to whoever runs it. Connect only an agent you'd show the song to.

Setting it up. The agent talks to a small helper, fledgetone mcp, that runs on your computer (it comes with Fledgetone's source: see docs/AGENT.md there for the two commands that build it and how to add it to your agent). Then:

1. Ask your agent to connect to Fledgetone. It gives you a code like K7QM-3XPD-9TBW.
2. In Fledgetone, choose View › Let an agent connect… (or search for it), type the code, and tick what the agent may do: it can always read the song; it can also see what you select, suggest changes and listen (render a few bars and measure their loudness and balance; nothing plays). Leave the port at 47123 unless your agent says another (it says the port with the code).
3. Connect. The header shows Agent connected; click it, or View › Suggestions, for the Suggestions panel. If the code was mistyped, type it again and press Try again: what's ticked at that moment is what the agent gets.

The agent never opens the panel or moves the keyboard focus. The header's Agent connected button (Suggestions when no agent is connected) shows how many suggestions are waiting for you, and a dot when the agent has sent a message you haven't seen; on the panel, Jump to new messages from your agent takes you to them.

Suggestions. Each one arrives as a card at the end of the Suggestions panel, marked From your agent: what the agent called it and why (in quotes: those are its words, not Fledgetone's), What changes in plain words, cautions in amber (a track much louder, the master pushed, a delay feeding back), and notes. Move the pointer over a card to see its tracks and bars tinted on the timeline. A card that has just appeared or moved ignores clicks for a second, so a click meant for another card never lands on it.

• Hear: Suggested and Now play the same bars looped, switching at the same place in the music (even when the suggestion changes the tempo), so you hear exactly what changes. They play every place the suggestion can be heard, one after another: the bars it changes, with the notes ringing out after them (for as long as the track's delay and reverb, the buses and returns it plays into and the master reverb and delay it sends to keep them sounding); wherever a track plays when it changes that track's level, sound, effects, routing or automation (a lane holds its value before and after its points); from where a tempo glide starts for a tempo change; the whole song for the tempo or the master (the card's What changes heading names them all). The studio also finds where it changes by ear: in the background (never while your song plays), or while it plays when you press Suggested or Now (you don't wait for it: the card says Finding where it changes…; Stop cancels it), it renders your song whole as it is and as suggested and compares them bar by bar, and any bar that sounds different is played too (if it finds one you haven't heard yet, the card says you heard it only in part). Bars on the card are numbered as the ruler numbers them, in any time signature. A song longer than 4 minutes is left to the rules above (and so is one the suggestion would make longer than 5 minutes), and the card says it wasn't checked by sound; if part of it may ring on longer than the studio can know (a plugin, or an instrument's release), Accept always asks for a second press. The bars the agent asked you to hear come too, if they fit. A before-and-after plays at most 64 bars and 90 seconds: a suggestion that can be heard in more than that plays as much as fits, and the card says which places you hear, which you don't, and which limit it was. Your song's playback stops first, and nothing in your song changes while you listen (no undo step, no autosave). A suggestion much louder than your song plays turned down to about 6 dB louder than it (in loudness), and the card says so. Stop stops it.
• Accept puts it in your song as one undo step: Edit › Undo (Ctrl+Z) takes it all back out. When that step is undone the card says Undone, and Redo makes it Accepted again; changing the same things back yourself doesn't count as undoing it. Dismiss throws it away.
• Listen first. Once you've heard a suggestion, one press of Accept puts it in. If you haven't heard it, the first press changes the button to Accept without listening: press it again (a separate press, not a double-click) within a few seconds to accept it anyway, or hear it first. It counts as heard only once Suggested has played through every place it can be heard, each to its end, at least once (switch to Now and back as often as you like, but each bar has to have played on Suggested): stopped early, or too long to hear at once, it's heard in part, the card says so (and which bars weren't), and Accept still asks for the second press. The card says whether you've heard it, and a press that doesn't count says why. Space never accepts (it says to press Enter).
• If you change the song while a suggestion waits (an edit, the swing, the intensity), it's checked again: if what it changes is untouched, it's made again on your song as it is now when you hear it, so you hear it again before it goes in (or use Accept without listening). If you edited something it changes, it's out of date and can't be accepted. If you open another song (New, Open, a link, Restore), the suggestions you had are for the other song and can't be accepted in this one; anything playing stops.

Each card names the agent that made it, even after you connect another. The names an agent gives (its own, and those of tracks, clips and markers) are shown in a box of their own, so whatever they say never reads as Fledgetone's words. Before the code is checked, the connection dialog says only Fledgetone's own words, never anything the program on that port sends.

The agent can also leave you messages on the panel (marked as from your agent, in quotes) and point at a track, a clip, some bars or a control: a ring for a few seconds, nothing pressed and the keyboard left where it was. Disconnect on the panel ends the connection; closing the tab does too.

Replying to your agent. You can write back: type in Message your agent… at the foot of the Suggestions panel and press Send (or Enter; Shift+Enter starts a new line). Ask a question, say what you'd like, or tell it to slow down. Your messages are marked You, the agent's From your agent, and an answer to one of yours shows which. Ask about this on a suggestion ties your next message to it (only on the cards of the agent connected now: another one can't read an earlier agent's suggestions). While you type, keys stay in the box: Space, letters, Delete and Ctrl+Z don't touch your song.

• What gets sent: only what you type, only when you press Send, and only to your agent's helper on your computer (your agent then sends it to whoever runs it, as with everything it reads). Your selection goes along only if you tick Include what I've selected for that message, and only if you let the agent see what you select.
• Where it is: each of your messages says Sent, then Seen by your agent once the agent has read it. With no agent connected it says Not sent — the agent isn't connected with Retry: it's never sent later without you pressing Retry. Once you connect again (maybe to another agent), earlier messages that weren't sent can't be retried: Put back in the box puts the words back, after anything you're writing, so you can send them as a new message (if both don't fit, the box is left as it is and says so). Your selection goes along on a retry only if the agent may still see it.
• Nothing is saved: the conversation is kept only while the tab is open (the helper forgets it when you disconnect). It's never put in your song or on disk.

If it doesn't connect. Chrome may ask whether the page can reach devices on your local network: allow it (the helper is on your computer). Safari and Brave may block the connection to a helper on your computer: then have the helper serve the studio itself (add --studio where your agent starts fledgetone mcp; docs/AGENT.md has the details) and open the address it gives (at 127.0.0.1:47200) on the same computer. That studio is the same app, but its saved songs and settings are its own, apart from fledgetone.com's: save a song as a file to move it between them. If another tab already has your agent connected, the dialog says so: disconnect it there first. If the Suggestions panel itself can't load (you're offline, say) or stops working, a note at the top offers Reload (your song is kept); Close puts it away until you open the panel again. The phone apps don't connect to agents.