Chat with Agents

The Chat page is the primary way to talk to Snippbot. A single conversation can host one or many agents, each with their own persona, memory, and model. You can address specific agents with @!-mentions, switch a room between cooperative and on-demand modes, run two conversations side by side, and turn any thread into a project.

Expand

This guide walks through the common workflows. For an exhaustive reference of every surface, see the Chat UI reference.

---

Concepts

A few terms are worth pinning down before you dive in.

Concept	What it means
Primary agent	The agent who created the conversation. Always shown first in the roster with a cyan ring. Immutable — switching the primary creates a new conversation.
Roster	The set of agents currently in the room. Includes the primary plus any agents you’ve added.
Lead	The agent that handles routing decisions in multi-agent modes. Defaults to the primary; can be reassigned.
Interaction mode	Solo, On-demand, or Collaborative. Controls how many agents reply per user message.
Execution mode	Plan / Auto / Approve. Controls how much autonomy the agent has when calling tools.
Active thinker	The single agent in a multi-agent room whose autonomous Jarvis cycles run.
View mode	Compact, Split, Split-Pane (multi-tab), and Focus. Layout choices for the chat surface.
@ mention	Type @ to insert a file reference; type @! to address a specific agent.

---

Start a conversation

1. Open Chat — Click Chat in the orbital sidebar, or visit http://localhost:18781/chat.

2. Pick an agent — Use the agent selector in the header. This agent becomes the primary for the conversation. Switching the selector resumes that agent’s most recent chat-sourced conversation, or creates a fresh one if none exist.

3. (Optional) Pick a model — Hover the agent’s avatar in the chat to open the Agent Hover Popover and override the preferred model from the inline dropdown. When no override is set, the conversation uses the site-wide default model from Settings → Providers.

4. Send a message — Type in the composer and press Enter. The first message auto-creates the conversation and auto-refines its title from your message preview.

Tip

The conversation title in the header is also a button — click it to open the history dropdown of this agent’s recent conversations.

---

Add a second agent

Multi-agent rooms let you mix experts in a single thread — for example, a researcher to dig up context and a coder to implement.

1. Open the pane roster toolbar — It’s the strip directly above the chat surface that shows the mode pill, cap pill, and roster avatars.

2. Click the inline + — At the right end of the roster avatar strip. The Add Agent dropdown opens.

3. Pick the agent to add — The list includes all agents you’ve created in Snippbot (Donna, Elon, Carl, your custom agents), minus the primary and anyone already in the room. If the list is empty, the dropdown shows a Create agent → shortcut to the Awakening flow.

4. Confirm the new avatar appears — The added agent renders to the right of the primary’s cyan-ringed avatar.

5. Switch the room to On-demand or Collaborative — Click the mode pill (first control in the toolbar) and pick the mode that fits.

Note

The primary’s cyan ring stays put — they’re always in the room and can’t be removed. The lead is a role that can move between agents independently of who’s primary.

---

Address a specific agent

When multiple agents are in the room, the composer’s @! typeahead lets you direct a message at one of them.

1. Type @! in the composer. The typeahead opens with agents-only results.

2. Pick the agent — Roster members are sorted first with an “in room” badge. Selecting one inserts a chip backed by @!handle.

3. Add the rest of your message and send.

Example:

@!architect please review the API design from the previous message,
then @!coder implement the highest-priority change.

If you mention an agent who isn’t in the room yet, the chip carries a “not in room” badge. On send, an inline confirm “Add @reviewer to the room?” appears — approve to add and continue, cancel to drop the mention.

Note

Typing @ alone shows a unified picker with Agents (roster first) and Files. Typing @! filters to agents only.

---

Manage the roster

All roster actions live on the Agent Hover Popover — hover any avatar in the pane roster toolbar (or any message bubble) to open it.

Promote to lead

The lead is the agent the room routes to when no explicit @!-mention applies, and the one that handles route_to(...) decisions in On-demand / Collaborative.

1. Hover the avatar of the agent you want to promote.
2. Click Promote to lead in the popover.

The previous lead is automatically demoted in the same transaction.

Remove an agent

1. Hover the avatar of a non-primary agent.
2. Click Remove from room.

Removing the current lead pauses the room until you pick a new lead from the surfaced prompt. The primary can’t be removed — they own the conversation.

---

Pick an execution mode

The execution-mode dropdown sits next to the composer. Mode is persisted per agent and per conversation.

Mode	When to use
Plan	Reviewing a strategy before letting the agent act. Read-only — the agent reasons but cannot run mutating tools. A banner above the input reminds you.
Auto	Trusted tasks where speed matters. Agent reads and writes freely without asking.
Approve	Sensitive codebases or new agents you don’t fully trust yet. Each write pauses on an inline approval card with Approve / Reject / Approve all.

1. Open the dropdown — Compact pill with a colored dot and the current mode name, to the left of the composer.
2. Pick the mode — A toast confirms the switch and the new mode persists for this conversation.
3. For Approve mode — Send your next message and watch the inline approval card appear before each write. Click Approve all to skip subsequent prompts in the same turn.

---

Set the turn cap

The turn cap pill (next to the mode pill) bounds how many agent replies a single user message can produce. This matters mostly in Collaborative rooms where agents can invite each other.

Option	Effect
Default	Use the interaction mode’s default cap (Solo: 1, On-demand: 1, Collaborative: 3).
10 / 20 / 40 / 60	Allow up to that many agent replies before the room stops.
No limit	Let the conversation wind down on its own.

Caution

Higher caps multiply per-turn cost. A Collaborative room with Cap: 60 and three speakers each averaging $0.04/turn can run to ~$2 per user message. Watch the conversation’s token totals if you set this high.

---

Open two conversations side by side

Split-pane mode is useful for “researcher in pane A, builder in pane B” workflows — each pane has its own roster, mode, and tab history.

1. Open a second tab — Click + at the end of the tab bar.

2. Layout auto-switches — Once two tabs exist, the page renders a left and right pane with a draggable divider.

3. Drag the divider — Adjust the ratio. Both panes have a 300px minimum.

4. Drive each pane independently — Each pane has its own header, roster toolbar, action buttons, bottom toolbar, Self-Talk toggle, and view-mode toggle.

The top-level view-mode toggle and bottom toolbar hide automatically in split-pane mode — every pane renders its own copies.

---

Use Self-Talk to peek at autonomous thinking

When the room is in Jarvis mode (the active-thinker slot is assigned to an agent whose default chat mode is human), you can watch the agent’s autonomous reasoning stream as it runs.

1. Confirm Jarvis mode — The brain-icon Self-Talk button appears in the header only when the active thinker is Jarvis-default. If you see a Classic chip on the active-thinker selector instead, that agent’s cycles won’t fire.

2. Open Self-Talk — Click the brain icon, or press Cmd/Ctrl + Shift + K. If the side panel is collapsed, the shortcut auto-opens it and switches to Split view.

3. Scan thought bubbles — Autonomous thoughts also surface in the chat stream with a pink Thought badge and a left-border accent.

4. Give feedback — Thumbs up / down on a thought bubble helps the agent learn.

In split-pane mode, each pane has its own Self-Talk toggle.

---

Convert a conversation into a project

If a chat is shaping into something you’d track as work, the bottom toolbar can turn it into a planning project with phases and tasks.

1. Click Convert to Project — In the bottom toolbar, when there’s at least one message.

2. Fill the modal — Project name, optional filesystem path, agent (defaults to the active agent), and model. The dialog seeds the project with up to the last 20 messages of context.

3. Generate — The page navigates to the new project’s edit screen pre-seeded with chat context. Edit the plan from there.

See the Projects guide for what happens next.

---

Apply team-generated files to a project

When a complex task triggers team orchestration, the chat shows a phase progress bar (Architect → Executor → Reviewer → Iteration) and an inline workspace file tree.

1. Open Workspace History — Folder icon in the header. The dropdown lists every workspace this conversation has produced and any chat-attached files.

2. Pick the workspace — Opens the standalone workspace viewer with syntax-highlighted previews.

3. Click Apply to Project — The dialog flags new files vs. overwrites.

4. Select which files to apply — Confirm and the files copy into the project directory.

---

Continue on another device

Pair your phone or another desktop and resume mid-conversation without losing context.

1. Open the transfer modal — Click the transfer icon in PaneActionButtons (top of header on single-pane; per-pane in split-pane).

2. Pick code or QR — Configurable under Settings → Chat. Code is easier to type on a paired phone; QR is faster when both devices are in the same room.

3. Approve the join from the original device — If your settings require approval, a SessionApprovalModal appears.

See Settings → Chat for the remote-session policy options.

---

Resume a conversation from a link

The Chat page accepts two URL parameters:

URL	Behavior
/chat?conversationId=<id>	Jumps directly into the given conversation in the active pane
/chat?agent=<agentId>	Pre-selects an agent (creates a fresh conversation on send)

Both work from bookmarks, History page links, or insight launches. If the conversation no longer exists the page recovers gracefully.

---

Tips

• Use Plan mode to read the agent’s strategy before letting it make any changes.
• Approve mode gives you control over every write — great for sensitive codebases or unfamiliar agents.
• Open a second tab to run two conversations side by side. Each tab has its own roster, mode, and self-talk state.
• Switch view modes (Compact / Split) to surface tool activity and self-talk in a side panel without losing the chat column.
• Drag files directly onto the chat area, paste images from your clipboard, or use Browse Assets to pick from previously uploaded community content.
• Type @ to insert a file reference, @! to direct a message at a specific agent.
• Press Cmd/Ctrl + Shift + K to peek at the agent’s autonomous thinking.
• Queue a follow-up while the agent is still streaming — it auto-sends when the current response ends.
• Use Generate Keypoints to summarize a long conversation into structured features, components, pages, and requirements.
• Convert to Project turns a planning chat into a real Snippbot project in one click.
• Use the transfer icon to continue this conversation on another device — configure rules in Settings → Chat.

---

Related

• Chat UI reference — every surface and control in detail
• Agents — what agents are and how they differ
• Voice Chat — TTS / STT setup and per-agent voices
• Autonomous Thinking — Jarvis cycles, the active thinker, and Self-Talk
• Use Sub-Agents — team orchestration concepts
• Settings → Chat — remote sessions, transfer rules
• Chat API — the HTTP / SSE surface that powers this page