🤖 feat: queue messages during streaming (#569)

Allows users to send multiple messages while AI is streaming without
interrupting the active response.



Demo:




https://github.com/user-attachments/assets/accde963-2076-4fd7-9941-34c90631b270




Closes #522.



A follow-up PR will add 'soft-interruptions', which take effect at the
end of the next content block (text-delta, reasoning-end, tool-result,
tool-error)



## Behavior



**While streaming:**

- Additional messages get queued instead of starting a new stream

- Queued message displays below streaming content with muted styling

- User can edit queued message before stream completes by pressing up
arrow (like regular messages) or the "Edit" button.



**On stream completion:**

- Queued messages auto-send immediately

- Queue supports text, images, and combined messages



**On stream abort (Ctrl+C):**

- Queued message restores to chat input for editing

- Images are preserved



## Known Issues

- **Compaction during streaming**: Cannot queue messages while
compaction is running. This will be fixed in a follow-up PR.



## Implementation



- **MessageQueue service** - Accumulates text, images, and options with
special handling for slash commands

- **AgentSession integration** - Stream-end triggers auto-send,
stream-abort triggers restore

- **QueuedMessage component** - Displays queued content with edit
functionality

- **IPC handlers** - Queue management and message routing

- **Test coverage** - 27 unit tests + 10 integration tests (requires
`ANTHROPIC_API_KEY`)



## Testing



```bash

# Unit tests (no API keys required)

bun test src/services/messageQueue.test.ts



# Integration tests (requires ANTHROPIC_API_KEY)

TEST_INTEGRATION=1 bun x jest tests/ipcMain/queuedMessages.test.ts

```



_Generated with `cmux`_

Author: ethanndickson

src/browser/App.stories.tsx

@@ -67,6 +67,7 @@ function setupMockAPI(options: {
       sendMessage: () => Promise.resolve({ success: true, data: undefined }),
       resumeStream: () => Promise.resolve({ success: true, data: undefined }),
       interruptStream: () => Promise.resolve({ success: true, data: undefined }),
+      clearQueue: () => Promise.resolve({ success: true, data: undefined }),
       truncateHistory: () => Promise.resolve({ success: true, data: undefined }),
       replaceChatHistory: () => Promise.resolve({ success: true, data: undefined }),
       getInfo: () => Promise.resolve(null),
@@ -1118,6 +1119,7 @@ export const ActiveWorkspaceWithChat: Story = {
               sendMessage: () => Promise.resolve({ success: true, data: undefined }),
               resumeStream: () => Promise.resolve({ success: true, data: undefined }),
               interruptStream: () => Promise.resolve({ success: true, data: undefined }),
+              clearQueue: () => Promise.resolve({ success: true, data: undefined }),
               truncateHistory: () => Promise.resolve({ success: true, data: undefined }),
               replaceChatHistory: () => Promise.resolve({ success: true, data: undefined }),
               getInfo: () => Promise.resolve(null),
@@ -1408,6 +1410,7 @@ These tables should render cleanly without any disruptive copy or download actio
               sendMessage: () => Promise.resolve({ success: true, data: undefined }),
               resumeStream: () => Promise.resolve({ success: true, data: undefined }),
               interruptStream: () => Promise.resolve({ success: true, data: undefined }),
+              clearQueue: () => Promise.resolve({ success: true, data: undefined }),
               truncateHistory: () => Promise.resolve({ success: true, data: undefined }),
               replaceChatHistory: () => Promise.resolve({ success: true, data: undefined }),
               getInfo: () => Promise.resolve(null),

src/browser/api.ts

@@ -225,6 +225,7 @@ const webApi: IPCApi = {
       invokeIPC(IPC_CHANNELS.WORKSPACE_RESUME_STREAM, workspaceId, options),
     interruptStream: (workspaceId, options) =>
       invokeIPC(IPC_CHANNELS.WORKSPACE_INTERRUPT_STREAM, workspaceId, options),
+    clearQueue: (workspaceId) => invokeIPC(IPC_CHANNELS.WORKSPACE_QUEUE_CLEAR, workspaceId),
     truncateHistory: (workspaceId, percentage) =>
       invokeIPC(IPC_CHANNELS.WORKSPACE_TRUNCATE_HISTORY, workspaceId, percentage),
     replaceChatHistory: (workspaceId, summaryMessage) =>

src/browser/components/AIView.tsx

@@ -27,6 +27,7 @@ import type { DisplayedMessage } from "@/common/types/message";
 import type { RuntimeConfig } from "@/common/types/runtime";
 import { useAIViewKeybinds } from "@/browser/hooks/useAIViewKeybinds";
 import { evictModelFromLRU } from "@/browser/hooks/useModelLRU";
+import { QueuedMessage } from "./Messages/QueuedMessage";
 
 interface AIViewProps {
   workspaceId: string;
@@ -141,8 +142,28 @@ const AIViewInner: React.FC<AIViewProps> = ({
     setEditingMessage({ id: messageId, content });
   }, []);
 
-  const handleEditLastUserMessage = useCallback(() => {
+  const handleEditQueuedMessage = useCallback(async () => {
+    const queuedMessage = workspaceState?.queuedMessage;
+    if (!queuedMessage) return;
+
+    await window.api.workspace.clearQueue(workspaceId);
+    chatInputAPI.current?.restoreText(queuedMessage.content);
+
+    // Restore images if present
+    if (queuedMessage.imageParts && queuedMessage.imageParts.length > 0) {
+      chatInputAPI.current?.restoreImages(queuedMessage.imageParts);
+    }
+  }, [workspaceId, workspaceState?.queuedMessage, chatInputAPI]);
+
+  const handleEditLastUserMessage = useCallback(async () => {
     if (!workspaceState) return;
+
+    if (workspaceState.queuedMessage) {
+      await handleEditQueuedMessage();
+      return;
+    }
+
+    // Otherwise, edit last user message
     const mergedMessages = mergeConsecutiveStreamErrors(workspaceState.messages);
     const lastUserMessage = [...mergedMessages]
       .reverse()
@@ -159,7 +180,7 @@ const AIViewInner: React.FC<AIViewProps> = ({
         element?.scrollIntoView({ behavior: "smooth", block: "center" });
       });
     }
-  }, [workspaceState, contentRef, setAutoScroll]);
+  }, [workspaceState, contentRef, setAutoScroll, handleEditQueuedMessage]);
 
   const handleCancelEdit = useCallback(() => {
     setEditingMessage(undefined);
@@ -458,6 +479,12 @@ const AIViewInner: React.FC<AIViewProps> = ({
                 />
               )}
             </div>
+            {workspaceState?.queuedMessage && (
+              <QueuedMessage
+                message={workspaceState.queuedMessage}
+                onEdit={() => void handleEditQueuedMessage()}
+              />
+            )}
           </div>
           {!autoScroll && (
             <button
@@ -479,7 +506,7 @@ const AIViewInner: React.FC<AIViewProps> = ({
           isCompacting={isCompacting}
           editingMessage={editingMessage}
           onCancelEdit={handleCancelEdit}
-          onEditLastUserMessage={handleEditLastUserMessage}
+          onEditLastUserMessage={() => void handleEditLastUserMessage()}
           canInterrupt={canInterrupt}
           onReady={handleChatInputReady}
         />

src/browser/components/ChatInput/index.tsx

@@ -96,6 +96,7 @@ function createTokenCountResource(promise: Promise<number>): TokenCountReader {
 
 // Import types from local types file
 import type { ChatInputProps, ChatInputAPI } from "./types";
+import type { ImagePart } from "@/common/types/ipc";
 export type { ChatInputProps, ChatInputAPI };
 
 export const ChatInput: React.FC<ChatInputProps> = (props) => {
@@ -225,16 +226,27 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
     [setInput]
   );
 
+  // Method to restore images to input (used by queued message edit)
+  const restoreImages = useCallback((images: ImagePart[]) => {
+    const attachments: ImageAttachment[] = images.map((img, index) => ({
+      id: `restored-${Date.now()}-${index}`,
+      url: img.url,
+      mediaType: img.mediaType,
+    }));
+    setImageAttachments(attachments);
+  }, []);
+
   // Provide API to parent via callback
   useEffect(() => {
     if (props.onReady) {
       props.onReady({
         focus: focusMessageInput,
         restoreText,
         appendText,
+        restoreImages,
       });
     }
-  }, [props.onReady, focusMessageInput, restoreText, appendText, props]);
+  }, [props.onReady, focusMessageInput, restoreText, appendText, restoreImages, props]);
 
   useEffect(() => {
     const handleGlobalKeyDown = (event: KeyboardEvent) => {
@@ -305,18 +317,31 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
     };
   }, []);
 
-  // Allow external components (e.g., CommandPalette) to insert text
+  // Allow external components (e.g., CommandPalette, Queued message edits) to insert text
   useEffect(() => {
     const handler = (e: Event) => {
-      const detail = (e as CustomEvent).detail as { text?: string } | undefined;
-      if (!detail?.text) return;
-      setInput(detail.text);
-      setTimeout(() => inputRef.current?.focus(), 0);
+      const customEvent = e as CustomEvent<{
+        text: string;
+        mode?: "append" | "replace";
+        imageParts?: ImagePart[];
+      }>;
+
+      const { text, mode = "append", imageParts } = customEvent.detail;
+
+      if (mode === "replace") {
+        restoreText(text);
+      } else {
+        appendText(text);
+      }
+
+      if (imageParts && imageParts.length > 0) {
+        restoreImages(imageParts);
+      }
     };
     window.addEventListener(CUSTOM_EVENTS.INSERT_TO_CHAT_INPUT, handler as EventListener);
     return () =>
       window.removeEventListener(CUSTOM_EVENTS.INSERT_TO_CHAT_INPUT, handler as EventListener);
-  }, [setInput]);
+  }, [appendText, restoreText, restoreImages]);
 
   // Allow external components to open the Model Selector
   useEffect(() => {
@@ -835,7 +860,7 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
         : KEYBINDS.INTERRUPT_STREAM_NORMAL;
       hints.push(`${formatKeybind(interruptKeybind)} to interrupt`);
     }
-    hints.push(`${formatKeybind(KEYBINDS.SEND_MESSAGE)} to send`);
+    hints.push(`${formatKeybind(KEYBINDS.SEND_MESSAGE)} to ${canInterrupt ? "queue" : "send"}`);
     hints.push(`${formatKeybind(KEYBINDS.OPEN_MODEL_SELECTOR)} to change model`);
     hints.push(`/vim to toggle Vim mode (${vimEnabled ? "on" : "off"})`);
 

src/browser/components/ChatInput/types.ts

@@ -1,9 +1,11 @@
+import type { ImagePart } from "@/common/types/ipc";
 import type { FrontendWorkspaceMetadata } from "@/common/types/workspace";
 
 export interface ChatInputAPI {
   focus: () => void;
   restoreText: (text: string) => void;
   appendText: (text: string) => void;
+  restoreImages: (images: ImagePart[]) => void;
 }
 
 // Workspace variant: full functionality for existing workspaces

src/browser/components/CommandPalette.tsx

@@ -197,7 +197,12 @@ export const CommandPalette: React.FC<CommandPaletteProps> = ({ getSlashContext
             shortcutHint: `${formatKeybind(KEYBINDS.SEND_MESSAGE)} to insert`,
             run: () => {
               const text = s.replacement;
-              window.dispatchEvent(createCustomEvent(CUSTOM_EVENTS.INSERT_TO_CHAT_INPUT, { text }));
+              window.dispatchEvent(
+                createCustomEvent(CUSTOM_EVENTS.INSERT_TO_CHAT_INPUT, {
+                  text,
+                  mode: "append",
+                })
+              );
             },
           })),
         },

src/browser/components/Messages/MessageRenderer.tsx

@@ -12,6 +12,7 @@ interface MessageRendererProps {
   message: DisplayedMessage;
   className?: string;
   onEditUserMessage?: (messageId: string, content: string) => void;
+  onEditQueuedMessage?: () => void;
   workspaceId?: string;
   isCompacting?: boolean;
 }

src/browser/components/Messages/MessageWindow.tsx

@@ -1,5 +1,5 @@
 import { cn } from "@/common/lib/utils";
-import type { DisplayedMessage, MuxMessage } from "@/common/types/message";
+import type { DisplayedMessage, MuxMessage, QueuedMessage } from "@/common/types/message";
 import { formatTimestamp } from "@/browser/utils/ui/dateTime";
 import { Code2Icon } from "lucide-react";
 import type { ReactNode } from "react";
@@ -19,7 +19,7 @@ export interface ButtonConfig {
 interface MessageWindowProps {
   label: ReactNode;
   variant?: "assistant" | "user";
-  message: MuxMessage | DisplayedMessage;
+  message: MuxMessage | DisplayedMessage | QueuedMessage;
   buttons?: ButtonConfig[];
   children: ReactNode;
   className?: string;

src/browser/components/Messages/QueuedMessage.tsx

@@ -0,0 +1,55 @@
+import React from "react";
+import type { ButtonConfig } from "./MessageWindow";
+import { MessageWindow } from "./MessageWindow";
+import type { QueuedMessage as QueuedMessageType } from "@/common/types/message";
+import { Pencil } from "lucide-react";
+
+interface QueuedMessageProps {
+  message: QueuedMessageType;
+  className?: string;
+  onEdit?: () => void;
+}
+
+export const QueuedMessage: React.FC<QueuedMessageProps> = ({ message, className, onEdit }) => {
+  const { content } = message;
+
+  const buttons: ButtonConfig[] = onEdit
+    ? [
+        {
+          label: "Edit",
+          onClick: onEdit,
+          icon: <Pencil />,
+        },
+      ]
+    : [];
+
+  return (
+    <>
+      <MessageWindow
+        label="Queued"
+        variant="user"
+        message={message}
+        className={className}
+        buttons={buttons}
+      >
+        {content && (
+          <pre className="text-subtle m-0 font-mono text-xs leading-4 break-words whitespace-pre-wrap opacity-90">
+            {content}
+          </pre>
+        )}
+        {message.imageParts && message.imageParts.length > 0 && (
+          <div className="mt-2 flex flex-wrap gap-2">
+            {message.imageParts.map((img, idx) => (
+              <img
+                key={idx}
+                src={img.url}
+                alt={`Attachment ${idx + 1}`}
+                className="border-border-light max-h-[300px] max-w-80 rounded border"
+              />
+            ))}
+          </div>
+        )}
+      </MessageWindow>
+    </>
+  );
+};

src/browser/stores/WorkspaceStore.ts

@@ -1,5 +1,5 @@
 import assert from "@/common/utils/assert";
-import type { MuxMessage, DisplayedMessage } from "@/common/types/message";
+import type { MuxMessage, DisplayedMessage, QueuedMessage } from "@/common/types/message";
 import { createMuxMessage } from "@/common/types/message";
 import type { FrontendWorkspaceMetadata } from "@/common/types/workspace";
 import type { WorkspaceChatMessage } from "@/common/types/ipc";
@@ -14,6 +14,8 @@ import {
   isStreamError,
   isDeleteMessage,
   isMuxMessage,
+  isQueuedMessageChanged,
+  isRestoreToInput,
 } from "@/common/types/ipc";
 import { MapStore } from "./MapStore";
 import { createDisplayUsage } from "@/common/utils/tokens/displayUsage";
@@ -32,6 +34,7 @@ import { createFreshRetryState } from "@/browser/utils/messages/retryState";
 export interface WorkspaceState {
   name: string; // User-facing workspace name (e.g., "feature-branch")
   messages: DisplayedMessage[];
+  queuedMessage: QueuedMessage | null;
   canInterrupt: boolean;
   isCompacting: boolean;
   loading: boolean;
@@ -111,6 +114,7 @@ export class WorkspaceStore {
   private historicalMessages = new Map<string, MuxMessage[]>();
   private pendingStreamEvents = new Map<string, WorkspaceChatMessage[]>();
   private workspaceMetadata = new Map<string, FrontendWorkspaceMetadata>(); // Store metadata for name lookup
+  private queuedMessages = new Map<string, QueuedMessage | null>(); // Cached queued messages
 
   /**
    * Map of event types to their handlers. This is the single source of truth for:
@@ -201,6 +205,36 @@ export class WorkspaceStore {
       aggregator.handleMessage(data);
       this.states.bump(workspaceId);
     },
+    "queued-message-changed": (workspaceId, _aggregator, data) => {
+      if (!isQueuedMessageChanged(data)) return;
+
+      // Create QueuedMessage once here instead of on every render
+      // Use displayText which handles slash commands (shows /compact instead of expanded prompt)
+      // Show queued message if there's text OR images (support image-only queued messages)
+      const hasContent = data.queuedMessages.length > 0 || (data.imageParts?.length ?? 0) > 0;
+      const queuedMessage: QueuedMessage | null = hasContent
+        ? {
+            id: `queued-${workspaceId}`,
+            content: data.displayText,
+            imageParts: data.imageParts,
+          }
+        : null;
+
+      this.queuedMessages.set(workspaceId, queuedMessage);
+      this.states.bump(workspaceId);
+    },
+    "restore-to-input": (workspaceId, _aggregator, data) => {
+      if (!isRestoreToInput(data)) return;
+
+      // Use INSERT_TO_CHAT_INPUT event with mode="replace"
+      window.dispatchEvent(
+        createCustomEvent(CUSTOM_EVENTS.INSERT_TO_CHAT_INPUT, {
+          text: data.text,
+          mode: "replace",
+          imageParts: data.imageParts,
+        })
+      );
+    },
   };
 
   // Cache of last known recency per workspace (for change detection)
@@ -305,6 +339,7 @@ export class WorkspaceStore {
       return {
         name: metadata?.name ?? workspaceId, // Fall back to ID if metadata missing
         messages: aggregator.getDisplayedMessages(),
+        queuedMessage: this.queuedMessages.get(workspaceId) ?? null,
         canInterrupt: activeStreams.length > 0,
         isCompacting: aggregator.isCompacting(),
         loading: !hasMessages && !isCaughtUp,