[feat] add image support in cli (#386)

Author: brandonkachen

bun.lock

@@ -35,15 +35,17 @@
     "@tanstack/react-query": "^5.62.8",
     "commander": "^14.0.1",
     "immer": "^10.1.3",
+    "jimp": "^1.6.0",
     "open": "^10.1.0",
     "pino": "9.4.0",
     "posthog-node": "4.17.2",
-    "string-width": "^7.2.0",
     "react": "^19.0.0",
     "react-reconciler": "^0.32.0",
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
+    "string-width": "^7.2.0",
+    "terminal-image": "^4.1.0",
     "unified": "^11.0.0",
     "yoga-layout": "^3.2.1",
     "zod": "^3.24.1",

cli/package.json

@@ -111,13 +111,19 @@ describe.skipIf(!sdkBuilt)('CLI End-to-End Tests', () => {
       await new Promise<void>((resolve) => {
         const timeout = setTimeout(() => {
           resolve()
-        }, 800)
+        }, 2000) // Increased timeout for CI environments
 
+        // Check both stdout and stderr - CLI may output to either
         proc.stdout?.once('data', () => {
           started = true
           clearTimeout(timeout)
           resolve()
         })
+        proc.stderr?.once('data', () => {
+          started = true
+          clearTimeout(timeout)
+          resolve()
+        })
       })
 
       proc.kill('SIGTERM')
@@ -139,13 +145,19 @@ describe.skipIf(!sdkBuilt)('CLI End-to-End Tests', () => {
       await new Promise<void>((resolve) => {
         const timeout = setTimeout(() => {
           resolve()
-        }, 800)
+        }, 2000) // Increased timeout for CI environments
 
+        // Check both stdout and stderr - CLI may output to either
         proc.stdout?.once('data', () => {
           started = true
           clearTimeout(timeout)
           resolve()
         })
+        proc.stderr?.once('data', () => {
+          started = true
+          clearTimeout(timeout)
+          resolve()
+        })
       })
 
       proc.kill('SIGTERM')

cli/src/__tests__/e2e-cli.test.ts

@@ -11,7 +11,11 @@ import {
 import { useShallow } from 'zustand/react/shallow'
 
 import { routeUserPrompt, addBashMessageToHistory } from './commands/router'
+import { addClipboardPlaceholder, addPendingImageFromFile } from './utils/add-pending-image'
+import { getProjectRoot } from './project-files'
 import { AnnouncementBanner } from './components/announcement-banner'
+import { hasClipboardImage, readClipboardImage, readClipboardText } from './utils/clipboard-image'
+import { showClipboardMessage } from './utils/clipboard'
 import { ChatInputBar } from './components/chat-input-bar'
 import { MessageWithAgents } from './components/message-with-agents'
 import { PendingBashMessage } from './components/pending-bash-message'
@@ -36,7 +40,7 @@ import {
   type ChatKeyboardState,
   createDefaultChatKeyboardState,
 } from './utils/keyboard-actions'
-import { useMessageQueue } from './hooks/use-message-queue'
+import { useMessageQueue, type QueuedMessage } from './hooks/use-message-queue'
 import { useQueueControls } from './hooks/use-queue-controls'
 import { useQueueUi } from './hooks/use-queue-ui'
 import { useChatScrollbox } from './hooks/use-scroll-management'
@@ -429,6 +433,7 @@ export const Chat = ({
   const inputMode = useChatStore((state) => state.inputMode)
   const setInputMode = useChatStore((state) => state.setInputMode)
   const askUserState = useChatStore((state) => state.askUserState)
+  const pendingImages = useChatStore((state) => state.pendingImages)
 
   const {
     slashContext,
@@ -542,31 +547,12 @@ export const Chat = ({
     clearQueue,
     isQueuePausedRef,
   } = useMessageQueue(
-    (content: string) => {
-      // Route queued messages through the router to handle bash commands, slash commands, etc.
-      return routeUserPrompt({
-        abortControllerRef,
+    (message: QueuedMessage) =>
+      sendMessageRef.current?.({
+        content: message.content,
         agentMode,
-        inputRef,
-        inputValue: content,
-        isChainInProgressRef,
-        isStreaming,
-        logoutMutation,
-        streamMessageIdRef,
-        addToQueue,
-        clearMessages,
-        saveToHistory: () => {}, // Already saved when queued
-        scrollToLatest,
-        sendMessage,
-        setCanProcessQueue,
-        setInputFocused,
-        setInputValue: () => {}, // Input already cleared when queued
-        setIsAuthenticated,
-        setMessages,
-        setUser,
-        stopStreaming,
-      })
-    },
+        images: message.images,
+      }) ?? Promise.resolve(),
     isChainInProgressRef,
     activeAgentStreamsRef,
   )
@@ -1032,8 +1018,42 @@ export const Chat = ({
       onExitApp: () => handleCtrlC(),
       onBashHistoryUp: navigateUp,
       onBashHistoryDown: navigateDown,
-      onDismissBashOverlay: () => {},
-      onCancelBashCommand: () => {},
+      onPasteImage: () => {
+        const placeholderPath = addClipboardPlaceholder()
+
+        setTimeout(() => {
+          if (!hasClipboardImage()) {
+            useChatStore.getState().removePendingImage(placeholderPath)
+            const text = readClipboardText()
+            if (text) {
+              setInputValue((prev) => {
+                const before = prev.text.slice(0, prev.cursorPosition)
+                const after = prev.text.slice(prev.cursorPosition)
+                return {
+                  text: before + text + after,
+                  cursorPosition: before.length + text.length,
+                  lastEditDueToNav: false,
+                }
+              })
+            }
+            return
+          }
+
+          const result = readClipboardImage()
+          if (!result.success || !result.imagePath) {
+            useChatStore.getState().removePendingImage(placeholderPath)
+            showClipboardMessage(result.error || 'Failed to paste image', {
+              durationMs: 3000,
+            })
+            return
+          }
+
+          const cwd = getProjectRoot() ?? process.cwd()
+          void addPendingImageFromFile(result.imagePath, cwd, placeholderPath)
+        }, 0)
+
+        return true
+      },
     }),
     [
       setInputMode,

cli/src/chat.tsx

@@ -0,0 +1,95 @@
+import { describe, test, expect } from 'bun:test'
+
+/**
+ * Tests for the handleImageCommand argument parsing behavior.
+ * 
+ * These tests verify the parsing logic independently of the actual
+ * validateAndAddImage implementation by testing the parsing function directly.
+ */
+
+// Extract the parsing logic that handleImageCommand uses
+// New simplified implementation: split on whitespace
+function parseImageCommandArgs(args: string): {
+  imagePath: string | null
+  message: string
+} {
+  const [imagePath, ...rest] = args.trim().split(/\s+/)
+  
+  if (!imagePath) {
+    return { imagePath: null, message: '' }
+  }
+  
+  return { imagePath, message: rest.join(' ') }
+}
+
+describe('handleImageCommand parsing', () => {
+  describe('argument parsing', () => {
+    test('parses image path only', () => {
+      const result = parseImageCommandArgs('./screenshot.png')
+      expect(result.imagePath).toBe('./screenshot.png')
+      expect(result.message).toBe('')
+    })
+
+    test('parses image path with message', () => {
+      const result = parseImageCommandArgs('./screenshot.png please analyze this')
+      expect(result.imagePath).toBe('./screenshot.png')
+      expect(result.message).toBe('please analyze this')
+    })
+
+    test('parses image path with multi-word message', () => {
+      const result = parseImageCommandArgs('./image.jpg what is in this picture?')
+      expect(result.imagePath).toBe('./image.jpg')
+      expect(result.message).toBe('what is in this picture?')
+    })
+
+    test('handles absolute paths with message', () => {
+      const result = parseImageCommandArgs('/path/to/file.png describe the UI')
+      expect(result.imagePath).toBe('/path/to/file.png')
+      expect(result.message).toBe('describe the UI')
+    })
+
+    test('trims whitespace from input', () => {
+      const result = parseImageCommandArgs('  ./image.png  ')
+      expect(result.imagePath).toBe('./image.png')
+      expect(result.message).toBe('')
+    })
+
+    test('handles multiple spaces between path and message', () => {
+      const result = parseImageCommandArgs('./image.png    hello world')
+      expect(result.imagePath).toBe('./image.png')
+      // The regex only captures content after the first whitespace group
+      expect(result.message).toBe('hello world')
+    })
+  })
+
+  describe('invalid input handling', () => {
+    test('returns null imagePath for empty input', () => {
+      const result = parseImageCommandArgs('')
+      expect(result.imagePath).toBeNull()
+      expect(result.message).toBe('')
+    })
+
+    test('returns null imagePath for whitespace-only input', () => {
+      const result = parseImageCommandArgs('   ')
+      expect(result.imagePath).toBeNull()
+      expect(result.message).toBe('')
+    })
+  })
+
+  describe('edge cases', () => {
+    test('handles filenames with extensions', () => {
+      const result = parseImageCommandArgs('image.jpeg')
+      expect(result.imagePath).toBe('image.jpeg')
+    })
+
+    test('handles relative paths', () => {
+      const result = parseImageCommandArgs('../screenshots/test.png')
+      expect(result.imagePath).toBe('../screenshots/test.png')
+    })
+
+    test('handles tilde paths', () => {
+      const result = parseImageCommandArgs('~/Downloads/image.png')
+      expect(result.imagePath).toBe('~/Downloads/image.png')
+    })
+  })
+})

cli/src/commands/__tests__/image.test.ts

@@ -1,13 +1,15 @@
+import { handleImageCommand } from './image'
 import { handleInitializationFlowLocally } from './init'
 import { handleReferralCode } from './referral'
 import { normalizeReferralCode } from './router-utils'
 import { handleUsageCommand } from './usage'
 import { useChatStore } from '../state/chat-store'
 import { useLoginStore } from '../state/login-store'
 import { getSystemMessage, getUserMessage } from '../utils/message-history'
+import { capturePendingImages } from '../utils/add-pending-image'
 
 import type { MultilineInputHandle } from '../components/multiline-input'
-import type { InputValue } from '../state/chat-store'
+import type { InputValue, PendingImage } from '../state/chat-store'
 import type { ChatMessage } from '../types/chat'
 import type { SendMessageFn } from '../types/contracts/send-message'
 import type { User } from '../utils/auth'
@@ -23,7 +25,7 @@ export type RouterParams = {
   isStreaming: boolean
   logoutMutation: UseMutationResult<boolean, Error, void, unknown>
   streamMessageIdRef: React.MutableRefObject<string | null>
-  addToQueue: (message: string) => void
+  addToQueue: (message: string, images?: PendingImage[]) => void
   clearMessages: () => void
   saveToHistory: (message: string) => void
   scrollToLatest: () => void
@@ -186,7 +188,8 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
         params.streamMessageIdRef.current ||
         params.isChainInProgressRef.current
       ) {
-        params.addToQueue(trimmed)
+        const pendingImages = capturePendingImages()
+        params.addToQueue(trimmed, pendingImages)
         params.setInputFocused(true)
         params.inputRef.current?.focus()
         return
@@ -212,6 +215,26 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
       clearInput(params)
     },
   },
+  {
+    name: 'image',
+    aliases: ['img', 'attach'],
+    handler: async (params, args) => {
+      const trimmedArgs = args.trim()
+
+      // If user provided a path directly, process it immediately
+      if (trimmedArgs) {
+        await handleImageCommand(trimmedArgs)
+        params.saveToHistory(params.inputValue.trim())
+        clearInput(params)
+        return
+      }
+
+      // Otherwise enter image mode
+      useChatStore.getState().setInputMode('image')
+      params.saveToHistory(params.inputValue.trim())
+      clearInput(params)
+    },
+  },
 ]
 
 export function findCommand(cmd: string): CommandDefinition | undefined {

cli/src/commands/command-registry.ts

@@ -0,0 +1,20 @@
+import { getProjectRoot } from '../project-files'
+import { validateAndAddImage } from '../utils/add-pending-image'
+
+/**
+ * Handle the /image command to attach an image file.
+ * Usage: /image <path> [message]
+ * Example: /image ./screenshot.png please analyze this
+ * 
+ * Returns the optional message as transformedPrompt (empty string if none).
+ * Errors are shown in the pending images banner with auto-remove.
+ */
+export async function handleImageCommand(args: string): Promise<string> {
+  const [imagePath, ...rest] = args.trim().split(/\s+/)
+  
+  if (imagePath) {
+    await validateAndAddImage(imagePath, getProjectRoot())
+  }
+  
+  return rest.join(' ')
+}