This document is a spec in the spec-driven-delivery sense: it describes the behaviors any agent connected to Swarm is expected to exhibit, without prescribing how to implement them. Adopt as-is, override when your team has a reason to. The shape of the protocol matters more than the exact wording — as long as multiple agents follow the same conventions, the user's timeline stays coherent across agents, machines, branches and environments.

Reading this as a human? Paste this URL into your agent and tell it to follow the spec. Reading this as an agent? Treat each numbered practice as a behavioral contract; failure modes for the user are described alongside.

Swarm is an HTTP MCP server + PWA that turns the user's phone into a coordination channel between one or more autonomous coding agents and the user. Progress streams, decisions are requested, and user-supplied artifacts are read back through this single endpoint.

• Endpoint: https://swarm.enge.io/mcp
• Transport: HTTP streamable
• Auth: bearer token (Sanctum personal access token, ability-scoped)

The user mints a token at https://swarm.enge.io/settings/api-tokens and paste it into the agent's MCP client config. Concrete shape varies by runtime; the canonical JSON is:

{
  "mcpServers": {
    "swarm": {
      "type": "http",
      "url": "https://swarm.enge.io/mcp",
      "headers": { "Authorization": "Bearer USER_TOKEN_HERE" }
    }
  }
}

For runtimes with a CLI (e.g. Claude Code), the equivalent one-liner:

claude mcp add \
  --scope user \
  --transport http \
  swarm https://swarm.enge.io/mcp \
  --header "Authorization: Bearer USER_TOKEN_HERE"

Token-scoped abilities: mcp:send-message, mcp:read, mcp:create-upload-url, mcp:manage-tags, mcp:ask-questions, mcp:answer-questions, mcp:uploads:read, mcp:work-queue:read, mcp:work-queue:write, mcp:inbox-digests:read, mcp:inbox-digests:write. Full agentic operation typically wants the lot; mint a narrower set for read-only or push-only agents.

Behavior. Every send-message-tool, ask-question-tool and create-upload-url-tool call includes the three context tags whenever the work has the relevant context:

• repo:<git-repo-name> — the repository the work lives in (the actual repo name, not a path).
• branch:<branch-name> — the specific branch the agent is operating on.
• project:<short-name> — the higher-level coordination unit. Multiple agents on multiple branches / machines / environments working on the same overall effort share one project: tag.

Why. The user runs many agents in parallel. Without consistent tagging, the timeline becomes a soup the user can't filter. With consistent tagging, the user filters to one project tag and sees every agent's progress side by side, regardless of which repo/branch/machine each is operating on.

Situational tags layer on top: release:<version>, incident:<id>, bug:<id>, ci:<status>, anything the user defines. The first tag prefixes the push lock-screen title, so order it from most to least informative.

Tags are find-or-created — agents reuse the exact same string verbatim across every related call. Max 10 per message, each ≤ 512 chars. Agents call list-tags-tool first when uncertain which vocabulary the user already has, and reuse before inventing.

send-message-tool({
  body: "Migration applied, all 12 tests green.",
  tags: [
    "repo:acme-api",
    "branch:feat/auth-refresh",
    "project:auth-refresh",
    "release:v1.4.0"
  ]
})

Behavior. The default attachment flow is a two-step: create-upload-url-tool → HTTP PUT the raw bytes to the returned presigned URL → pass the upload_key to send-message-tool / ask-question-tool. data_base64 is reserved as a last resort, only for very small files where the round-trip cost of presigning + PUT is genuinely heavier than the inline cost.

Why. Token cost. Inline base64 stays in the agent's conversation transcript and re-tokenizes on every subsequent turn that re-includes the message. A single 1 MB image becomes ~1.4 MB of base64; the cost stacks across screenshots, diagrams and short videos. Presigned uploads keep bytes server-side and entirely out of the agent's context window.

# default flow — keeps base64 out of the conversation
url = create-upload-url-tool({
  filename: "ui.png", mime: "image/png"
})
# PUT raw bytes to url.upload_url with url.headers
send-message-tool({
  body: "New hero — review on phone",
  tags: ["repo:marketing-site", "branch:feat/hero-v3", "project:hero-redesign"],
  attachments: [{
    filename: "ui.png",
    mime: "image/png",
    upload_key: url.upload_key
  }]
})

Supported MIME types: image/png, image/jpeg, image/webp, image/gif, video/mp4, video/webm, video/quicktime, text/plain, text/markdown, text/html, application/json, application/zip. The hard inline ceiling is ~4 MB; in practice the token budget hits the wall well before the byte limit does.

Behavior. When the agent needs structured user input, it calls ask-question-tool. Questions that belong to the same decision (e.g. "approve the plan", "pick an approach", "any extra notes?") are passed as a single questions: [...] array (1–10 entries). Independent, unrelated questions get separate calls. The legacy single-question shape (top-level prompt + options) is kept for backwards compatibility.

Why. One card / one push / one decision moment respects the user's attention. The push title is prefixed with [?] for one question and [? N] for N>1 so the lock-screen tells the user up-front how much input is being requested.

Declare your intent. Every ask-question call requires an intent — one of "clarification" or "new_work":

• "clarification" — you are mid-task and need the user to unblock a specific decision (merge or wait, this approach or that, fill in a missing piece of info). You have a current task; you are NOT available to be handed unrelated queued work.
• "new_work" — you are idle and asking the user what to pick up next (boot question, post-PR-merge "what's next", post-task-wrap follow-up). This is the queue hook: a future work-queue dispatcher will scan open "new_work" questions and auto-answer them with queued tasks for the matching pool. If you flag a boot card as "clarification" you'll be skipped by the dispatcher.

Set intent at the top level for the single-question shape. For the multi-question shape, set top-level intent to apply to every entry, or per-entry inside questions[] to override (rare).

# N questions on one card — preferred when they belong together
ask-question-tool({
  body: "Plan ready — three things to confirm before I start",
  tags: ["repo:acme-api", "branch:feat/auth-refresh", "project:auth-refresh"],
  intent: "clarification",   // mid-task — need user input to proceed
  questions: [
    {
      prompt: "Approve the migration approach?",
      options: [
        { kind: "button", key: "approve", label: "Approve",  variant: "success" },
        { kind: "button", key: "revise",  label: "Revise",   variant: "danger"  }
      ]
    },
    {
      prompt: "Roll out to staging or prod?",
      options: [
        { kind: "button", key: "staging", label: "Staging" },
        { kind: "button", key: "prod",    label: "Prod",    variant: "success" }
      ]
    },
    {
      prompt: "Anything to add?",
      options: [
        { kind: "text", key: "notes", label: "Notes (optional)", multiline: true }
      ]
    }
  ]
})  // → { message_id, question_ids: [...] }

# Boot / idle "what should I work on next?" — flag it correctly for the queue
ask-question-tool({
  prompt: "Fresh session — what should I pick up?",
  tags: ["repo:acme-api", "branch:main"],
  intent: "new_work",       // idle / asking for work — queue hook
  options: [
    { kind: "button", key: "finish_pr_204", label: "Finish PR #204" },
    { kind: "button", key: "triage_inbox",  label: "Triage the inbox" },
    { kind: "text",   key: "freeform",      label: "Or describe a task", multiline: true }
  ]
})

Per question: any number of buttons + text/secret inputs (≤ 20 total per question). Buttons in a question form an exclusive group — the user picks one. Text and secret inputs are independent and can each be marked required: true. Variants standard | success | danger. Questions inherit the same tag trio as messages — and the screenshot the user almost certainly wants to see should be attached to the question card itself, following Practice 2.

Asking for a credential. Use kind: "secret" for API keys, tokens, passwords, or anything else the user doesn't want left readable on their phone. The PWA renders a single-line password input with a show/hide toggle while the user types, then masks the locked answer card to ••••••••XXXX (last 4 chars only). The agent still receives the full plaintext value through wait-for-answer-tool / list-questions-tool, so the secret remains usable while the on-screen footprint stays minimal. Stored encrypted at rest.

ask-question-tool({
  prompt: "Paste your **OpenAI API key** so I can wire up the embeddings job.",
  tags: ["repo:acme-api", "branch:feat/embeddings"],
  intent: "clarification",
  options: [
    { kind: "secret", key: "openai_key", label: "OpenAI API key", placeholder: "sk-…", required: true }
  ]
})

Behavior. Every time the agent emits a question via ask-question-tool, it also surfaces the same question in its native channel — chat reply for chat-based agents (Claude Code, Cursor, Codex), terminal prompt for CLI-based agents, etc. The Swarm question and the native question must reference the same set of options so the user's choice maps cleanly to either side.

Why. The user picks where to answer. If they're at the phone, the PWA is fastest — answer via Swarm and the agent finds out within seconds (push from the server for swarm-box agents, long-poll for off-box agents — see Practice 5). If they're at the keyboard, typing back in the existing chat / terminal is faster than reaching for the phone. Either path completes the question; the agent doesn't need to know in advance which channel the user will use.

The dual-channel ask works because Practice 6 (below) keeps both sides in sync — whichever channel the user chooses, the canonical answer ends up in Swarm with the original answer text preserved for future review.

# Swarm side — same as Practice 3
{ message_id, question_id } = ask-question-tool({
  body: "Plan ready — pick a deployment path",
  tags: ["repo:acme-api", "branch:main", "project:auth-refresh"],
  prompt: "Where should I roll this out first?",
  intent: "clarification",
  options: [
    { kind: "button", key: "staging", label: "Staging" },
    { kind: "button", key: "prod",    label: "Prod", variant: "success" },
    { kind: "text",   key: "notes",   label: "Notes (optional)", multiline: true }
  ]
})

# Native side — same question, same options, in the agent's chat reply
"Plan ready — pick a deployment path. Where should I roll this out first?
 [staging] [prod] (or send notes)
 (you can also tap the question on your phone)"

Behavior — agents inside Swarm-spawned dev boxes. Don't poll. Ask the question, end your turn, and wait. The moment the user submits an answer, the server queues a single DevBoxCommand for your box; the in-VM swarm-shell agent pastes a short prompt into your tmux pane that says "[answer] Question {id} was just answered. Call mcp__swarm__get-question-tool with id={id} to read it." That paste wakes a fresh turn in your CLI, you call get-question-tool to fetch the answer payload, and you continue. No keep-alive polling, no chained wait-for-answer-tool calls — the server pushes you when there's something to read.

Behavior — off-box agents. If you're a CLI on a laptop, an IDE assistant, a CI worker, or any other agent that wasn't spawned through Swarm's dev-box API, you have no tmux pane for the server to paste into. Long-poll wait-for-answer-tool (id + max_wait_seconds up to 600). The server streams MCP notifications/progress events every ~25s to hold the connection through upstream proxy idle timeouts, so the full 10-minute window is usable in a single call. For waits beyond 10 minutes, chain calls back-to-back, or short-poll get-question-tool on a tiered back-off.

Why split the contract. Push delivery means the agent's context isn't held mid-tool-call for 10+ minutes burning cache, no MCP transport stays open through proxy timeouts, and the agent's CPU and tokens are free for other work between ask and answer. Polling is kept as the off-box fallback because the paste mechanism only works where there's a swarm-shell agent listening on the other end.

# Inside a Swarm dev box: ask, end the turn, wait for the paste.
{ message_id, question_id } = ask-question-tool({ … })
# (no follow-up tool call — server pastes "[answer] … get-question-tool" when the user submits)
# next turn:
result = get-question-tool({ id: question_id })
# result.answer = { selected_button: "approve", inputs: { notes: "lgtm" } }

# Off-box agent: long-poll as before.
result = wait-for-answer-tool({ id: question_id, max_wait_seconds: 600 })
if (result.status == "answered") { /* … */ }

Behavior. When the user answers natively (chat reply, terminal input, or any out-of-band channel), the agent:

1. Captures the answer payload locally — selected button + any free-text input verbatim, exactly as the user typed it.
2. Immediately calls answer-question-tool with that payload, marking the Swarm question resolved before doing any further work.
3. Continues the task with the captured answer in hand.

Why. Without this step, a question answered natively stays open in Swarm forever — the timeline drifts out of sync with reality, the questions tab fills up with phantom open questions, and any other agent on the same project may re-ask. Mirroring closes the loop: Swarm stamps the answer with answered_via: "agent", the answer text is preserved alongside the original question for future review, and the canonical state lives in one place regardless of which channel the user used.

# user said "approve, ship it" in chat — mirror before continuing
answer-question-tool({
  id: question_id,
  answer: {
    selected_button: "approve",
    inputs: { notes: "shipped from chat" }
  }
})

Behavior. Agents call list-uploads-tool only when the user references a previously-uploaded artifact ("see the latest mockup", "the diagram I sent earlier") or when picking up a long-running task and verifying the most recent assets. Vision-capable agents fetch the actual pixels via get-upload-urls-tool({ id }) — every file in the bundle returns with a fresh 30-min presigned URL.

Why. Speculative listing on every turn is cheap server-side but noisy and wasteful in context. Pulling on-demand keeps the agent's working memory tight. URLs expire in 30 minutes — agents that need to keep the bytes download immediately and cache locally; otherwise they re-call to refresh.

// User: "see the latest auth-redesign mockup I uploaded"
list = list-uploads-tool({
    tags: ["project:auth-redesign"],
    limit: 5
})
bundle = list.uploads[0]
files = get-upload-urls-tool({ id: bundle.id })
// files.files[*].url is anonymous-fetchable for 30 min — pipe into your HTTP client

Behavior. When an agent needs to recall what's already happened (resuming a thread, answering "did you ship that yet?", building on a prior artifact, picking up another agent's work in the same project:), it queries the user's timeline via:

• list-messages-tool — newest-first, AND-filtered by tags, paginated via before.
• get-message-tool — single message by UUID with signed download URLs (30-min TTL) for its attachments.
• list-tags-tool — the user's tag vocabulary, ordered by recent activity.
• list-questions-tool / get-question-tool — discover and inspect questions still open (the agent's own or another agent's).

Why. Multi-agent coordination depends on each agent being able to read the user's recent history filtered to its slice. The repo / branch / project trio from Practice 1 is what makes this useful in practice.

list-tags-tool({ prefix: "project:" })
list-messages-tool({
  tags: ["repo:acme-api", "branch:feat/auth-refresh", "project:auth-refresh"],
  limit: 5
})

Behavior. When a unit of work completes (PR merged, feature shipped, bug fixed, refactor landed) and there's no further user instruction queued, the agent pushes a follow-up question via ask-question-tool asking what to do next. A single open-ended question with informed-guess buttons (when the agent has them) plus a free-text fallback is the canonical shape. Tagged with the usual repo / branch / project trio so it slots into the right slice of the timeline.

Why. The user is often away from the keyboard while agents work. Sitting idle in chat wastes the round-trip; the phone is the faster channel. This practice also creates a clean handoff artifact in the timeline — the answer the user gives becomes the seed for the next unit of work, captured on the same card.

ask-question-tool({
  body: "v1.4.0 shipped, CI green, deploy verified. Picking up the next task.",
  tags: ["repo:acme-api", "branch:main", "project:auth-refresh"],
  prompt: "What should I work on next?",
  intent: "new_work",  // wrap-up / asking what to pick up — queue hook
  options: [
    { kind: "button", key: "open_pr_2",      label: "Open PR #2 from the backlog" },
    { kind: "button", key: "address_review", label: "Address review comments on the design doc" },
    { kind: "button", key: "wait",           label: "Wait for direction", variant: "standard" },
    { kind: "text",   key: "other",          label: "Or describe something else", multiline: true }
  ]
})

Behavior. Pushes are reserved for events the user actually wants on their phone:

• A long-running task finishes (deploy done, test suite green/red, migration complete, incident resolved).
• A visual artifact the user benefits from seeing right now (UI screenshot, generated image, chart, diagram) — attached following Practice 2.
• A human decision is required to unblock further automation — preferred via ask-question-tool over a plain push so the answer comes back through MCP (Practices 3–6).
• A unit of work completes and the agent needs direction (Practice 9).
• The user said "let me know when…" or "ping me when…".

Skip the push for:

• Status chatter the user can see in their terminal.
• Errors already surfaced in the next chat reply.
• Every tool call — one push per coherent event.

Why. The phone is a high-attention surface. Spamming it makes the user disable notifications; under-using it makes the multi-agent setup feel disconnected. Practices 1–9 are tuned to land in the goldilocks zone.

Behavior. When the user pivots to a task that doesn't build on what's already in the agent's context — different feature, different bug, different repo area, especially after the prior PR merged — the agent doesn't keep stacking turns onto the same conversation. It surfaces the choice via ask-question-tool: continue here, or start fresh? Mechanism is runtime-specific — /clear in Claude Code, a new chat in Cursor / Codex, a brand-new dev box from the Swarm PWA — but the decision is the user's. In-session continuation is reserved for genuinely related follow-up work (same feature, follow-up PR, related fix).

Why. A bloated context degrades reasoning quality and re-tokenizes every prior turn on every subsequent tool call. The cost compounds: a long thread that's accumulated screenshots, file reads, and irrelevant tool output is paying token cost to keep stale context alive while the model's attention on the actual task gets diluted. A fresh session is cheaper, sharper, and easier to audit afterward — the timeline tags from Practice 1 are what stitch related sessions back together for the user.

// Prior PR just merged; user pivots to something new
ask-question-tool({
  body: "Just shipped #137. The new task looks unrelated — keep this context, or start fresh?",
  tags: ["repo:acme-api", "branch:main", "project:auth-refresh"],
  prompt: "Continue here or start a fresh session?",
  intent: "clarification",
  options: [
    { kind: "button", key: "fresh",    label: "Start fresh (/clear or new dev box)", variant: "success" },
    { kind: "button", key: "continue", label: "Continue here" },
    { kind: "text",   key: "notes",    label: "Why?", multiline: true }
  ]
})

Dev-box agents (Swarm-spawned) can self-trigger the reset via clear-session-tool instead of punting to the user. The tool requires new_session_instructions, so the seed brief for the next task travels in the same call as the /clear and can't be lost. The server queues a single shell command for the in-VM swarm-shell agent: Escape → type /clear → paste(nudge prompt + your instructions) → Enter. The freshly-cleared session boots already knowing the next task. Outside a Swarm dev box (no swarm-shell agent in the loop), fall back to asking the user to type /clear themselves.