Tutorial

Add a one-click email action by describing it.

You don't write JSON. You don't pick from a menu. You describe — in English — the action you wish lived on your message view, and SwarmMarshal builds it. About two minutes start to finish.

Vibes Plain English Built-in handlers No code

What we're building

Pick a noisy sender — a newsletter you forgot you signed up for, an alerting system that pings you ten times a day, a marketing list that won't quit. We're going to add a button to the message view that, in one click, sweeps everything from that sender into Trash across every account.

We won't write any code. We won't open a settings page. We'll just tell SwarmMarshal what we want.

Step 1

Open Vibes and describe what you want

From the SwarmMarshal sidebar, click Vibes. You'll see a text box that asks "What should this vibe do?"

Type something like:

Add a button to my message view that sweeps every message from this sender to Trash in one click.

Click Build vibe. SwarmMarshal's vibe builder reads your sentence, recognizes you're asking for a button on an existing surface (not a new tracker), picks the right built-in handler, wires it to your message context, and saves the result.

About fifteen seconds later, your new vibe appears in the list below the form.

Other phrasings that work the same way:

"Add an archive-everything-from-sender button to the message view."
"When I open a noisy newsletter, give me one click to mark every message from that sender as read."
"Stick a 'wipe their backlog' action in the message toolbar."

Step 2

Open any message — try the new button

No restart, no extra step. The vibe is live the moment Build vibe finishes.

Open your inbox. Click any email from a noisy sender.
Look at the toolbar above the message. The magic-wand AI button is on the left. Right next to it, you'll now see a puzzle-piece icon — that's your Vibes dropdown.
Click the puzzle piece. The dropdown shows every contribution from every vibe that applies to this message. Yours is in there, with the label you described and the vibe's name as a small caption beneath it.
Click your action. A toast confirms how many messages were swept. Future mail from that sender keeps arriving normally — this was a one-time cleanup, not a permanent block.

Heads up — the button is context-aware.

Open a draft instead and the puzzle-piece icon hides itself. The builder noticed your action only makes sense when there's a sender to act on, and wired in a context guard for you. You'll see this same behavior any time the underlying message doesn't have what the action needs.

Step 3

Refine it the same way you built it

Don't like the label? Want a different action? Just say so.

On the Vibes page, find the vibe you just built. Each vibe has an Edit instruction box. Type what you want changed in plain English:

Change the label to "Wipe their backlog" and add a second button that just marks them all read instead of trashing them.

SwarmMarshal updates the vibe in place. Your message view now shows two buttons under the same vibe in the dropdown — pick whichever fits the moment.

What just happened, briefly

The model behind the magic

For when "type a sentence" isn't enough — these are the moving parts you might want to know about.

Built-in handlers

The dangerous code — moving messages, marking read, sweeping Trash — lives inside SwarmMarshal as handlers. Vibes don't write that code; they declare a button that calls a handler. So a vibe can never do anything SwarmMarshal hasn't already shipped a vetted handler for.

Context tokens

Your button passes the current message's sender, source, and account into the handler at click time. The builder picks the right tokens automatically — you don't think about them unless you want to.

Context guards

The button hides on messages where it doesn't apply (drafts, no-sender cases). The builder reads your sentence, infers what the action needs, and wires the guard for you.

Editable, not magical

The vibe is a small JSON definition behind the scenes — you can open it, tweak the icon or the label, and save. The next "Edit instruction" you type works against that JSON. Plain English in, plain English to refine.

Reference

What the builder can wire today

Right now, vibe-built buttons can call any of these built-in actions. More extension points and handlers ship in regular updates.

If you say something like…	The builder picks this handler
"Sweep every message from this sender to Trash" / "Wipe their backlog"	`inbox.cleanup_by_sender`
"Archive everything from this sender" / "Move all from sender to Archive"	`inbox.archive_all_from_sender`
"Mark every message from this sender as read" / "Clear unread for this sender"	`inbox.mark_all_from_sender_read`

If you ask for something the available handlers can't do — say, "tag this thread with #urgent" — the builder will tell you that action isn't wired yet rather than guess. New handlers are added as SwarmMarshal grows; vibes you built keep working when they ship.

For the curious

Sharing a vibe someone else built

If a friend or coworker hands you a .json file, you can install it without having to recreate it from scratch.

Vibes can be exported as a single JSON file and re-imported on another SwarmMarshal install. On the Vibes page, click Import bundle…, pick the file, review what it contains, and install. SwarmMarshal warns you before replacing anything you already have.

This is the right path for sharing — not the right path for creating. If you want a new vibe, describe it and let the builder write the JSON for you.