# Chat

Conversations in Insulin support streaming responses, tool execution, plan approvals, model selection, attachments, memory, and cross-surface threads.

---

## Conversations

Each conversation is a multi-turn thread between you and an agent. Conversations are persisted automatically and appear in the sidebar for easy access. You can have multiple conversations open and switch between them.

![The Insulin Chat app — agents and channels in the sidebar, a streaming conversation, and the composer with the thinking toggle, mic, and attach controls](images/02-insulin-chat.png)

Each agent or channel view has a tab bar with **Messages**, **Files**, and **Jobs** — the same three whether you are in a solo agent chat or a [channel](./5.channels.md). The **Files** tab lists the attachments in the thread. The **Jobs** tab surfaces [jobs](./6.jobs.md): in a solo chat, that agent's own scheduled and on-demand jobs; in a channel, the jobs belonging to the agents that are members of it.

When you open a fresh solo chat, the empty state shows the agent's **welcome message** and a set of clickable **conversation-starter** buttons — click one to begin without typing.

Insulin also supports thread events through a live stream. This lets the UI update while an agent is running, while a channel is active, or while a paused run is waiting for an approval.

## Message Types

- **User messages** — Your inputs, including text, file references, and images.
- **Assistant messages** — Responses from the agent, streamed in real time as they are generated.
- **System messages** — Status updates, such as when an agent is switched or a tool completes execution.

## The Composer

The composer is the input bar at the bottom of the conversation. It holds the controls for everything you send:

- **Text with @mentions and /slash commands** — Type your message; `@` and `/` open inline pickers (see below).
- **Mic / voice** — Dictate a message instead of typing. The button shows a live elapsed timer while recording; stop to insert the transcribed text.
- **Attach (paperclip)** — Add files for the agent to read. You can also drag and drop files onto the composer or paste them.
- **Thinking toggle** — The Brain button turns [extended thinking](#extended-thinking) on or off for the session.
- **Send / Stop** — Send your message, or stop a response that is still streaming.

### File Attachments

Attach files by clicking the paperclip, dragging them onto the composer, or pasting them. Files upload before the message is sent and appear as attachment chips you can remove before sending.

| Limit | Value |
|-------|-------|
| Files per message | Up to 10 |
| Size per file | Up to 25 MB |

Before sending, each attachment shows as a chip you can remove. Attachments become viewable once the message is sent (see [Attachments in a Thread](#attachments-in-a-thread)).

### Slash Commands

Type `/` at the start of the composer to see the commands available for the current agent. The list includes the agent's built-in skills (for example, `/skill-creator`) plus any [skills](./7.marketplace.md) you have enabled, each slugified from its name. Selecting a command inserts it into your message.

One command is built in everywhere: **`/clear`** starts a fresh chat for the current agent or channel (see [Resetting a Conversation](#resetting-a-conversation)).

### @Mentions

Type `@` to mention a participant. In a [channel](./5.channels.md), this addresses a specific agent so it answers your message. Clicking an `@agent` mention in a message switches you to that agent's solo chat.

## Model Selection

Insulin selects the model for you — there is no per-conversation model picker. Each agent runs on the models available to it and **fails over automatically**: if a model call fails — a provider outage, a usage limit, or a rejected key — the turn retries on your next connected provider, so a single provider problem doesn't stall the conversation.

Which models an agent can draw on depends on its **ownership**:

- **The built-in Insulin assistant** and **Personal (only-you) agents** run on **your connected providers only** — the models from the LLM providers you've connected under **Settings → Integrations** (bring-your-own-key). If you haven't connected a provider yet, Insulin can't run and prompts you to connect one first.
- **Organization agents** can additionally fall back to a **Suger-hosted** model, so an organization keeps a working model even before it connects its own provider.

See [Agents](./3.agents.md) for how an agent's ownership and its configured **Default model** determine which models it uses.

### Where you set the model

There is no picker in the composer, but you do still choose the model — just once, not per message.

**For the built-in Insulin assistant:** open a chat with Insulin and click the **pencil** button in the conversation header (its accessible label reads *Insulin model settings*). A panel slides out with a **Models** section listing every model your connected providers make available.

1. Search or scroll to the model you want
2. **Click its row** — that makes it Insulin's default
3. The row you picked now carries a **Default** badge

Insulin runs that model first, then fails over to your other connected models from there. The same panel is where you find out you have nothing to pick from: with no provider connected it reads *"Connect a provider to use Insulin"* and offers a **Connect a provider** link.

**For a custom agent:** the model is a field on the agent itself. Set **Default model** in the agent's own settings — see [Agents](./3.agents.md).

![The Insulin agent settings panel — the Models list with each model and its provider, the selected one marked Default, and the note that Insulin runs on your own connected providers and fails over between them](images/18-model-settings.png)

### When a model fails over

Failover is surfaced, not silent. When a turn switches models and then succeeds, the reply carries a short italic note at the end naming both models, in this form:

> *`first-model` hit its usage limit — continued with `second-model`.*

The note reads *was unavailable* instead of *hit its usage limit* when the switch was caused by an error — a provider outage or a rejected key — rather than a quota.

When there is nothing left to fail over to, the turn stops and says why:

- **One model is out of quota.** A usage-limit card appears in the thread — *"You've hit the usage limit for `<model>`."* — plus *"Your limit resets at `<time>`"* when the provider reports one. The card links to that provider's usage page, or points you at Settings when the model was Suger-hosted.
- **Every connected model is limited.** You get a message naming the model you hit first, listing the others that are limited too, and the time the first limit resets, with a suggestion to check your providers' usage pages or try again once a limit clears.

## Streaming Responses

Agent responses stream token by token as they are generated. You can read the response as it appears without waiting for the full message to complete.

## Extended Thinking

When extended thinking is enabled, the agent shows its reasoning process before delivering a final answer. The thinking steps appear in a collapsible section above the response. This helps you understand the agent's logic and verify its approach on complex tasks.

Toggle thinking on or off with the **Brain** button in the composer. The setting applies to the session and is remembered in your browser.

## Tool Calls

Agents can execute tools — external actions like querying data, calling APIs, or running code. When a tool is invoked during a conversation, you see:

- **Running** — The tool call is in progress, with a spinner and the tool name displayed.
- **Success** — The tool completed and its output is shown inline.
- **Error** — The tool failed, with the error message displayed.

Tool call details are expandable so you can inspect inputs and outputs.

## Plan Approvals

For multi-step tasks, an agent may present a plan before executing. The plan lists the steps the agent intends to take. You can:

- **Approve** the plan to let the agent proceed
- **Reject** or modify the plan before execution

This gives you control over complex workflows before any actions are taken.

## Tool Approvals

Some tool calls pause for your explicit approval before they run. When one does, a **Tool Approval Required** card appears in the thread. It names the tool, shows the arguments it would be called with, and explains why it stopped to ask. Two buttons:

- **Allow** — the tool runs and the turn carries on.
- **Deny** — the tool is not called.

Once you answer, the card keeps a badge recording what you chose: **Approved** or **Rejected**. If you leave it alone, the request times out after about three minutes, the card is marked **Expired**, and nothing is sent.

![A Tool Approval Required card in a conversation — the wrench icon and heading, the numbered reason listing every action the approval covers, the Tool name, an Args block showing the JSON the tool was called with, and Allow / Deny in the footer](images/30-tool-approval.png)

:::warning
**Know where the approval gate is armed.** The card is offered only in an **interactive solo chat in the web workspace, on the main thread**. It is *not* offered — and the action is *not* held back — in:

- a [channel](./5.channels.md),
- a Slack or Microsoft Teams DM,
- a reply written inside a [sub-thread](#sub-threads).

Those surfaces can't render the card or send your decision back, so the turn proceeds without pausing. Treat the approval card as a guardrail on the one surface that can show it, not as a workspace-wide guarantee that every sensitive action will wait for you.
:::

## Plan Progress

When an agent executes a multi-step plan, a progress tracker shows the status of each step:

| Status | Meaning |
|--------|---------|
| **Pending** | Step has not started yet |
| **In progress** | Step is currently executing |
| **Completed** | Step finished successfully |
| **Failed** | Step encountered an error |
| **Skipped** | Step was bypassed (e.g., due to a prior failure) |

The progress tracker updates in real time as the agent works through the plan.

## Long-running work

Some requests take more than one exchange to finish. "Reconcile last quarter's entitlements and write up what doesn't match" isn't one answer — it's a stretch of work. Ask for something like that and the agent may keep going across many turns until the job is done, rather than stopping at the end of its first reply.

What you see is just the conversation. Each piece of progress arrives as an **ordinary message in the thread**, in order, indistinguishable from any other agent reply. There is no separate progress view to keep open and nothing to poll — close the window, come back later, and the messages are waiting for you.

**You steer it in plain English.** There are no controls for this; you simply write another message:

- *"Actually, only look at AWS."* — the agent applies your change from its next step onward and carries on with the same objective.
- *"Stop."* — the agent stops the work and confirms in one line. *"Cancel"*, *"pause"*, and *"drop it"* are read the same way.

Your message is picked up even while the agent is mid-step, so you never have to wait for a gap to redirect it. In a [channel](./5.channels.md) the same is true: the work belongs to the conversation, so it's steered by writing in the channel.

## Memory

Insulin maintains memory across conversations:

- **Short-term memory** — Context from the current conversation, including earlier messages and tool results.
- **Long-term memory** — Persistent knowledge the agent retains across conversations, such as your preferences, decisions, and recurring instructions. Long-term memories are categorized as **fact**, **preference**, **decision**, **context**, or **learned**.

Memory recall happens automatically — when the agent surfaces relevant past context, you see a memory recall indicator showing the number of memories retrieved and their content. Memory confidence decays over time, so older memories that are no longer reinforced gradually become less prominent.

You can also manage long-term memory directly: review the stored memories, delete individual ones, or clear them all in bulk.

## Connection Status

The chat interface shows a **Connecting…** banner while it establishes a connection to the AI service. Once connected, streaming is active and the agent can respond.

If the connection drops briefly, the client reconnects on its own in the background — no banner is shown and no action is needed on your part.

## Sub-Threads

Within a conversation, you can branch into sub-threads to explore a topic without disrupting the main conversation flow. Sub-threads appear as nested discussions tied to a specific message.

How you get into one depends on where you are:

| Way in | Solo chat | Channel |
|--------|-----------|---------|
| Hover a message, then click **Reply in thread** | Yes — starts a new sub-thread, or reopens the existing one | Not offered |
| Click the **N replies** badge on a message | Yes | Yes — this is the only way in |

In a channel, an agent's reply is delivered into a sub-thread and the parent message grows a **1 reply** / **N replies** badge you click to read it. **Sending a message in a channel no longer pops the side panel open by itself** — it used to interrupt whatever you were reading. Open the panel yourself while a reply is still being written and it streams live from that point.

You can rename a sub-thread, or ask Insulin to regenerate its title from the conversation. Renaming and title regeneration are available to the sub-thread's owner.

## Unread Messages

**Organization channels** in the sidebar carry an unread count, so you can see where the conversation moved on while you were away. The badge counts up to 99 and then reads **99+**.

Nothing else accumulates unread counts — not personal channels, not your one-on-one chats with an agent, and not sub-threads. Those are places only you and your own agents write, so a badge there would only ever be counting your own conversation back at you.

## Attachments in a Thread

Files you attach in the composer are uploaded and shown as attachment chips before you send. Once sent, they belong to the thread and appear in its **Files** tab, where they are listed and can be downloaded. Click an attachment on a sent message to open it in the [Preview](./1.getting-started.md) app — PDFs, images, and video render there.

## Quick Replies

Agents may offer quick reply suggestions — pre-written response options you can click instead of typing. These appear as buttons below the agent's message and are useful for common follow-up actions.

## Draft Preservation

If you start typing a message and navigate away from the conversation, your draft is preserved. When you return, your unsent message is restored in the composer. Your scroll position is preserved the same way, per conversation.

## Message Pagination

Long conversations load messages incrementally. As you scroll toward the top, earlier messages load automatically. When you scroll away from the bottom of the conversation, a floating **jump to latest** button appears so you can return to the newest message in one click.

## Slack and Teams

When Slack or Microsoft Teams is connected for your organization, Insulin can receive messages from those surfaces and mirror agent replies back to the same conversation context. Slack and Teams are **personal DM bots** for the built-in Insulin assistant — you chat with the assistant one-on-one, not in a shared channel. The web, Slack, and Teams DM surfaces share the same underlying Insulin thread, so work can continue across tools. (For multi-agent group discussions inside Insulin, see [Channels](./5.channels.md).)

## Resetting a Conversation

To start over with a clean slate, send the **`/clear`** command in the composer. This starts a fresh chat for the current agent or channel context. Your previous messages remain in their own thread — `/clear` simply begins a new conversation.