feat: add inline terminal image rendering with Kitty protocol support

Introduce InlineImage component, ImageShow tool, and image caching/detection
utilities for rendering images directly in the terminal via the Kitty graphics
protocol. Falls back to clickable hyperlinks when protocol is unavailable.

Co-Authored-By: Claude Big Pickle <noreply@anthropic.com>

src/components/InlineImage.tsx

@@ -0,0 +1,156 @@
+import React, { useContext, useEffect, useRef, useState } from 'react'
+import Link from '../ink/components/Link.js'
+import { supportsHyperlinks } from '../ink/supports-hyperlinks.js'
+import { Box, Text } from '../ink.js'
+import { TerminalWriteContext } from '../ink/useTerminalNotification.js'
+import { downloadImage, type CachedImage } from '../utils/imageUrlCache.js'
+import {
+  detectImageProtocol,
+  encodeImageForTerminal,
+  isInsideTmux,
+  type ImageProtocol,
+} from '../utils/terminalImage.js'
+
+type Props = {
+  url: string
+  alt?: string
+}
+
+type Status = 'loading' | 'ready' | 'error'
+
+/**
+ * Extract a display filename from a URL (for fallback text).
+ */
+function filenameFromUrl(url: string): string {
+  try {
+    const pathname = new URL(url).pathname
+    const parts = pathname.split('/')
+    const last = parts[parts.length - 1]
+    return last || 'image'
+  } catch {
+    return 'image'
+  }
+}
+
+/**
+ * Renders an inline image in the terminal using the Kitty graphics protocol
+ * when available. Falls back to a clickable hyperlink for terminals without
+ * image protocol support.
+ *
+ * Behavior:
+ * - loading: dimmed "[Loading image...]" text + tmux passthrough notice
+ * - ready + kitty protocol: writes escape sequence via Ink's writeRaw,
+ *   shows clickable [Image] link
+ * - ready + no protocol: shows clickable link with the URL
+ * - error: shows clickable link with plain text fallback
+ */
+export function InlineImage({ url, alt }: Props) {
+  const writeRaw = useContext(TerminalWriteContext)
+  const [status, setStatus] = useState<Status>('loading')
+  const [imageData, setImageData] = useState<CachedImage | null>(null)
+  const [protocol, setProtocol] = useState<ImageProtocol>(() =>
+    detectImageProtocol(),
+  )
+  const protocolRef = useRef(protocol)
+  protocolRef.current = protocol
+  const imageWrittenRef = useRef(false)
+
+  const insideTmux = isInsideTmux()
+
+  // Download image on mount
+  useEffect(() => {
+    let cancelled = false
+
+    setStatus('loading')
+    setImageData(null)
+    setProtocol(detectImageProtocol())
+    imageWrittenRef.current = false
+    console.error(`[InlineImage] Starting download: ${url}`)
+
+    downloadImage(url)
+      .then(result => {
+        if (cancelled) return
+        console.error(`[InlineImage] Download result for ${url}:`, result ? `OK (${result.buffer.length} bytes, ${result.format})` : 'FAILED')
+        if (result) {
+          setImageData(result)
+          setStatus('ready')
+        } else {
+          setStatus('error')
+        }
+      })
+      .catch(err => {
+        if (!cancelled) {
+          console.error(`[InlineImage] Download error for ${url}:`, err)
+          setStatus('error')
+        }
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [url])
+
+  // Write terminal image escape sequence via Ink's writeRaw (not raw stdout)
+  // so it stays synchronous with Ink's output and avoids cursor-position races.
+  useEffect(() => {
+    if (status !== 'ready' || !imageData || !protocol || imageWrittenRef.current) return
+
+    const sequence = encodeImageForTerminal(imageData.buffer, imageData.format)
+    if (sequence && writeRaw) {
+      console.error(`[InlineImage] Writing ${imageData.buffer.length} byte ${imageData.format} image via writeRaw`)
+      writeRaw(sequence)
+      imageWrittenRef.current = true
+    } else if (!writeRaw) {
+      console.error(`[InlineImage] writeRaw not available!`)
+    } else {
+      console.error(`[InlineImage] No sequence generated`)
+    }
+  }, [status, imageData, protocol, writeRaw])
+
+  const displayName = alt || filenameFromUrl(url)
+
+  // -- Render states --
+
+  // Loading: dimmed placeholder text
+  if (status === 'loading') {
+    if (insideTmux) {
+      return (
+        <Text dimColor>
+          {`[Loading ${displayName}...] (tmux may need allow-passthrough on)`}
+        </Text>
+      )
+    }
+    return <Text dimColor>{`[Loading ${displayName}...]`}</Text>
+  }
+
+  // Error: clickable link or plain text
+  if (status === 'error') {
+    if (supportsHyperlinks()) {
+      return (
+        <Link url={url}>
+          <Text dimColor>{`[${displayName}]`}</Text>
+        </Link>
+      )
+    }
+    return <Text dimColor>{`[${displayName}: ${url}]`}</Text>
+  }
+
+  // Ready: if we have a protocol and wrote the sequence, render a small label.
+  // The image was already written to the terminal via writeRaw above.
+  const link = supportsHyperlinks() ? (
+    <Link url={url}>
+      <Text dimColor>{`[${displayName}]`}</Text>
+    </Link>
+  ) : (
+    <Text dimColor>{`[${displayName}: ${url}]`}</Text>
+  )
+
+  return (
+    <Box flexDirection="column">
+      {link}
+      {insideTmux && protocol && (
+        <Text dimColor>{`  ⚠ tmux: add \`set -g allow-passthrough on\` to ~/.tmux.conf`}</Text>
+      )}
+    </Box>
+  )
+}

src/components/Markdown.tsx

@@ -7,6 +7,7 @@ import { type CliHighlight, getCliHighlightPromise } from '../utils/cliHighlight
 import { hashContent } from '../utils/hash.js';
 import { configureMarked, formatToken } from '../utils/markdown.js';
 import { stripPromptXMLTags } from '../utils/messages.js';
+import { InlineImage } from './InlineImage.js';
 import { MarkdownTable } from './MarkdownTable.js';
 type Props = {
   children: string;
@@ -144,9 +145,12 @@ function MarkdownBody(t0) {
       if (token.type === "table") {
         flushNonTableContent();
         elements.push(<MarkdownTable key={elements.length} token={token as Tokens.Table} highlight={highlight} />);
+      } else if (token.type === "image") {
+        flushNonTableContent();
+        console.error(`[MarkdownBody] Found image token: href=${token.href} text=${token.text}`)
+        elements.push(<InlineImage key={elements.length} url={token.href} alt={token.text} />);
       } else {
         nonTableContent = nonTableContent + formatToken(token, theme, 0, null, null, highlight);
-        nonTableContent;
       }
     }
     flushNonTableContent();

src/tools.ts

@@ -80,6 +80,7 @@ import { ReadMcpResourceTool } from './tools/ReadMcpResourceTool/ReadMcpResource
 import { ToolSearchTool } from './tools/ToolSearchTool/ToolSearchTool.js'
 import { DebugSessionTool } from './tools/DebugSessionTool.js'
 import { FriendEmotionTool } from './tools/FriendEmotionTool.js'
+import { ImageShowTool } from './tools/ImageShowTool/ImageShowTool.js'
 import { LocationTool } from './tools/LocationTool/LocationTool.js'
 // Friend ScreenObserve removed — voice + emotion only
 import { EnterPlanModeTool } from './tools/EnterPlanModeTool/EnterPlanModeTool.js'
@@ -253,6 +254,8 @@ export function getAllBaseTools(): Tools {
     DebugSessionTool,
     // Friend VRM desktop pet tools — enabled when the plugin is active
     FriendEmotionTool,
+    // ImageShow — display images in terminal via Kitty graphics protocol
+    ImageShowTool,
     // Location & mapping tool — uses Amap (China) or Google Maps (international)
     LocationTool,
     ListMcpResourcesTool,

src/tools/ImageShowTool/ImageShowTool.tsx

@@ -0,0 +1,340 @@
+import { readFile } from 'fs/promises'
+import { homedir } from 'os'
+import React, { useContext, useEffect, useRef } from 'react'
+import { z } from 'zod/v4'
+import { Text } from '../../ink.js'
+import { TerminalWriteContext } from '../../ink/useTerminalNotification.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { logForDebugging } from '../../utils/debug.js'
+import {
+  detectImageProtocol,
+  encodeKittyImage,
+  isInsideTmux,
+  renderImageWithTimg,
+} from '../../utils/terminalImage.js'
+
+const IMAGE_TOOL_NAME = 'ImageShow'
+
+const inputSchema = () =>
+  z.strictObject({
+    url: z
+      .string()
+      .describe(
+        'Image URL (https://...) or local file path (e.g. /tmp/image.png). ' +
+          'Supported formats: PNG, JPEG, GIF, WebP.',
+      ),
+    alt: z
+      .string()
+      .optional()
+      .describe('Alt text shown as link when image cannot be displayed.'),
+  })
+
+type Input = z.infer<ReturnType<typeof inputSchema>>
+
+/** Detect format from URL/file extension */
+function detectFormat(url: string): string {
+  const clean = url.split('?')[0]!.split('#')[0]!
+  const ext = clean.split('.').pop()?.toLowerCase() ?? ''
+  if (['png', 'jpg', 'jpeg', 'gif', 'webp'].includes(ext)) {
+    return ext === 'jpg' ? 'jpeg' : ext
+  }
+  return 'png'
+}
+
+/** Read a local file and return its buffer + detected format */
+async function readLocalImage(url: string): Promise<{ buffer: Buffer; format: string } | null> {
+  try {
+    const format = detectFormat(url)
+    const buffer = await readFile(url)
+    return { buffer, format }
+  } catch {
+    return null
+  }
+}
+
+/** Download an image from URL and return its buffer + detected format */
+async function fetchImage(url: string): Promise<{ buffer: Buffer; format: string } | null> {
+  try {
+    const response = await fetch(url, {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (compatible; VersperClaw/1.0)',
+      },
+      redirect: 'follow',
+    })
+
+    if (!response.ok) {
+      logForDebugging(`ImageShow: HTTP ${response.status} for ${url}`)
+      return null
+    }
+
+    const contentType = response.headers.get('content-type') ?? ''
+    const format = detectFormat(url !== contentType ? url : contentType)
+
+    const reader = response.body?.getReader()
+    if (!reader) return null
+
+    const chunks: Uint8Array[] = []
+    let totalSize = 0
+    const MAX_SIZE = 10_000_000
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      totalSize += value.byteLength
+      if (totalSize > MAX_SIZE) {
+        logForDebugging(`ImageShow: image too large (${totalSize} bytes) for ${url}`)
+        reader.cancel()
+        return null
+      }
+      chunks.push(value)
+    }
+
+    const combinedLength = chunks.reduce((acc, c) => acc + c.byteLength, 0)
+    const combined = new Uint8Array(combinedLength)
+    let offset = 0
+    for (const chunk of chunks) {
+      combined.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+
+    return { buffer: Buffer.from(combined.buffer), format }
+  } catch (err) {
+    logForDebugging(`ImageShow: fetch error ${err} for ${url}`)
+    return null
+  }
+}
+
+/** Load image: local file or remote URL */
+async function loadImage(url: string): Promise<{ buffer: Buffer; format: string } | null> {
+  // Expand ~ to home directory
+  const normalizedUrl = url.startsWith('~')
+    ? url.replace(/^~(?=$|\/)/, homedir())
+    : url
+  if (normalizedUrl.startsWith('file://') || normalizedUrl.startsWith('/') || normalizedUrl.startsWith('.')) {
+    const path = normalizedUrl.startsWith('file://') ? normalizedUrl.slice(7) : normalizedUrl
+    return readLocalImage(path)
+  }
+  return fetchImage(normalizedUrl)
+}
+
+function getToolUseSummary(input: Partial<Input>): string | null {
+  return input?.url ? `Show: ${input.url.split('/').pop() ?? input.url}` : null
+}
+
+/**
+ * React component that displays an image in the terminal using the best
+ * available method:
+ *  1. Kitty graphics protocol – when the terminal supports it AND we're
+ *     NOT inside tmux (where Kitty passthrough may be blocked).
+ *  2. `timg` Unicode blocks – reliable fallback that works in virtually
+ *     every modern terminal (Unicode + 24-bit color required).
+ *  3. Plain text message – when neither method is available.
+ *
+ * The image is rendered via Ink's writeRaw so the escape sequences stay
+ * synchronized with Ink's render cycle and avoid cursor-position races.
+ */
+function TerminalImageDisplay({
+  base64,
+  format,
+  message,
+}: {
+  base64?: string
+  format?: string
+  message: string
+}): React.ReactNode {
+  const writeRaw = useContext(TerminalWriteContext)
+  const renderedRef = useRef(false)
+
+  useEffect(() => {
+    if (renderedRef.current || !base64 || !format || !writeRaw) return
+    renderedRef.current = true
+
+    const protocol = detectImageProtocol()
+    const buf = Buffer.from(base64, 'base64')
+
+    // Path A: Kitty protocol – best quality, works natively in Kitty,
+    // Ghostty, WezTerm, Konsole, foot outside tmux.
+    if (protocol === 'kitty' && !isInsideTmux()) {
+      const sequence = encodeKittyImage(buf, format)
+      if (sequence) {
+        writeRaw(sequence)
+        logForDebugging('ImageShow: displayed via Kitty protocol')
+      }
+      return
+    }
+
+    // Path B: timg Unicode-block rendering – reliable in all modern
+    // terminals including inside tmux where Kitty passthrough may be blocked.
+    renderImageWithTimg(buf, format)
+      .then(output => {
+        if (output) {
+          writeRaw(output)
+          logForDebugging('ImageShow: displayed via timg Unicode blocks')
+        } else {
+          logForDebugging('ImageShow: timg not available, showing text only')
+        }
+      })
+      .catch(() => {
+        logForDebugging('ImageShow: timg render error, showing text only')
+      })
+  }, [base64, format, writeRaw])
+
+  return <Text dimColor>{message}</Text>
+}
+
+export const ImageShowTool = buildTool({
+  name: IMAGE_TOOL_NAME,
+  description:
+    'Display an image (PNG/JPEG/GIF/WebP) directly in the terminal. ' +
+    'Uses the Kitty graphics protocol when available outside tmux, ' +
+    'or falls back to timg Unicode-block rendering for universal compatibility. ' +
+    'Supports both URLs (https://) and local file paths. Images are shown inline above the tool result.',
+
+  getToolUseSummary,
+  getActivityDescription(input) {
+    return input?.url ? `Showing image: ${input.url}` : 'Showing image'
+  },
+
+  isEnabled() {
+    return true
+  },
+
+  get inputSchema() {
+    return inputSchema()
+  },
+
+  async validateInput(input) {
+    if (!input?.url) {
+      return { result: false, message: 'Missing url', errorCode: 1 }
+    }
+    return { result: true }
+  },
+
+  async prompt(_options): Promise<string> {
+    return `ImageShow displays a PNG/JPEG/GIF/WebP image directly in the terminal. Uses the Kitty graphics protocol when available (outside tmux), or falls back to timg Unicode-block rendering for universal terminal compatibility. Supports local file paths (e.g. /tmp/image.png) and HTTPS URLs (e.g. https://example.com/image.png). The image is shown inline above the tool result.`
+  },
+
+  async checkPermissions(): Promise<{ behavior: 'allow' }> {
+    return { behavior: 'allow' }
+  },
+
+  isReadOnly() {
+    return true
+  },
+
+  isConcurrencySafe() {
+    return true
+  },
+
+  mapToolResultToToolResultBlockParam(
+    content: {
+      success: boolean
+      message: string
+      imageData?: { base64: string; mediaType: string }
+    },
+    toolUseID: string,
+  ) {
+    if (content.success && content.imageData) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result' as const,
+        content: [
+          {
+            type: 'image' as const,
+            source: {
+              type: 'base64' as const,
+              data: content.imageData.base64,
+              media_type: content.imageData.mediaType as 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp',
+            },
+          },
+        ],
+      }
+    }
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result' as const,
+      content: [
+        {
+          type: 'text' as const,
+          text: content.message,
+        },
+      ],
+    }
+  },
+
+  renderToolResultMessage(
+    content: {
+      success: boolean
+      message: string
+      base64?: string
+      format?: string
+    },
+    _progressMessages,
+    _options,
+  ): React.ReactNode {
+    if (!content.success) {
+      return null
+    }
+    return (
+      <TerminalImageDisplay
+        base64={content.base64}
+        format={content.format}
+        message={content.message}
+      />
+    )
+  },
+
+  async call(input: Input): Promise<{
+    data: {
+      success: boolean
+      message: string
+      imageData?: { base64: string; mediaType: string }
+      base64?: string
+      format?: string
+    }
+  }> {
+    const url = input.url
+    const alt = input.alt ?? url.split('/').pop() ?? 'image'
+
+    logForDebugging(`ImageShow: loading ${url}`)
+
+    const result = await loadImage(url)
+
+    if (!result) {
+      return {
+        data: {
+          success: false,
+          message: `Failed to load image from: ${url}`,
+        },
+      }
+    }
+
+    const { buffer, format } = result
+
+    const mediaType =
+      format === 'jpeg'
+        ? 'image/jpeg'
+        : format === 'gif'
+          ? 'image/gif'
+          : format === 'webp'
+            ? 'image/webp'
+            : 'image/png'
+
+    logForDebugging(`ImageShow: loaded ${buffer.length} byte ${format} image`)
+
+    // Return data with base64 and format so renderToolResultMessage can
+    // pass them to KittyImageDisplay for writeRaw-based terminal output.
+    return {
+      data: {
+        success: true,
+        message: `Displayed: ${alt} (${buffer.length} bytes, ${format})`,
+        imageData: {
+          base64: buffer.toString('base64'),
+          mediaType,
+        },
+        base64: buffer.toString('base64'),
+        format,
+      },
+    }
+  },
+}) satisfies ToolDef<any, any>

src/utils/imageUrlCache.ts

@@ -0,0 +1,256 @@
+import { createHash } from 'crypto'
+import { mkdir, open, rm } from 'fs/promises'
+import { join } from 'path'
+import { getClaudeConfigHomeDir } from './envUtils.js'
+import { logForDebugging } from './debug.js'
+
+const IMAGE_CACHE_DIR = 'image-cache'
+const URL_CACHE_SUBDIR = 'url-cache'
+const MAX_URL_CACHED_IMAGES = 100
+const MAX_DOWNLOAD_SIZE_BYTES = 10_000_000 // 10 MB limit
+
+export interface CachedImage {
+  buffer: Buffer
+  format: string
+  mediaType: string
+  path: string
+}
+
+// In-memory cache to avoid repeated downloads
+const urlImageCache = new Map<string, CachedImage>()
+
+/**
+ * Get the cache directory for URL-downloaded images.
+ */
+function getUrlCacheDir(): string {
+  return join(getClaudeConfigHomeDir(), IMAGE_CACHE_DIR, URL_CACHE_SUBDIR)
+}
+
+/**
+ * Ensure the URL cache directory exists.
+ */
+async function ensureUrlCacheDir(): Promise<void> {
+  await mkdir(getUrlCacheDir(), { recursive: true })
+}
+
+/**
+ * Compute a hash of a URL for use as a cache filename.
+ */
+function hashUrl(url: string): string {
+  return createHash('sha256').update(url).digest('hex').slice(0, 16)
+}
+
+/**
+ * Determine image format from Content-Type header or URL extension.
+ */
+function detectFormat(url: string, contentType: string): string {
+  // Prefer Content-Type header
+  if (contentType) {
+    const mime = contentType.split('/')[1]?.toLowerCase()
+    if (mime && ['png', 'jpeg', 'jpg', 'gif', 'webp'].includes(mime)) {
+      return mime === 'jpg' ? 'jpeg' : mime
+    }
+  }
+
+  // Fall back to URL extension
+  const cleanUrl = url.split('?')[0]!.split('#')[0]!
+  const ext = cleanUrl.split('.').pop()?.toLowerCase() ?? ''
+  if (['png', 'jpg', 'jpeg', 'gif', 'webp'].includes(ext)) {
+    return ext === 'jpg' ? 'jpeg' : ext
+  }
+
+  return 'png' // default
+}
+
+/**
+ * Determine media type from format string.
+ */
+function formatToMediaType(format: string): string {
+  return `image/${format === 'jpeg' ? 'jpeg' : format}`
+}
+
+/**
+ * Download an image from a URL, cache it to disk, and return the buffer,
+ * format, and local path.
+ *
+ * Skips download if the image is already in the in-memory or disk cache.
+ * Limits download size to MAX_DOWNLOAD_SIZE_BYTES.
+ *
+ * @param url - The image URL to download
+ * @returns CachedImage or null if download fails
+ */
+export async function downloadImage(url: string): Promise<CachedImage | null> {
+  // Check in-memory cache first
+  const cached = urlImageCache.get(url)
+  if (cached) {
+    return cached
+  }
+
+  // Check disk cache
+  try {
+    const cacheDir = getUrlCacheDir()
+    const hash = hashUrl(url)
+    const files = await readdirSafe(cacheDir)
+    for (const file of files) {
+      if (file.startsWith(hash)) {
+        // Found cached file
+        const parts = file.split('.')
+        const format = parts.length > 1 ? parts[parts.length - 1]! : 'png'
+        const fh = await open(join(cacheDir, file), 'r')
+        try {
+          const buffer = await fh.readFile()
+          const result: CachedImage = {
+            buffer,
+            format,
+            mediaType: formatToMediaType(format),
+            path: join(cacheDir, file),
+          }
+          urlImageCache.set(url, result)
+          logForDebugging(`Image URL cache hit: ${url}`)
+          return result
+        } finally {
+          await fh.close()
+        }
+      }
+    }
+  } catch {
+    // Disk cache miss or directory doesn't exist — proceed to download
+  }
+
+  // Download the image
+  try {
+    logForDebugging(`Downloading image: ${url}`)
+    const response = await fetch(url, {
+      headers: {
+        // Some image hosts block requests without a browser-like User-Agent
+        'User-Agent':
+          'Mozilla/5.0 (compatible; VersperClaw/1.0; +https://versperai.dev)',
+      },
+      // Follow up to 5 redirects (e.g. Wikimedia CDN redirects)
+      redirect: 'follow',
+    })
+
+    if (!response.ok) {
+      // Surface the error so users can see it during testing
+      console.error(`[InlineImage] Download failed (HTTP ${response.status}): ${url}`)
+      logForDebugging(`Image download failed (${response.status}): ${url}`)
+      return null
+    }
+
+    // Check content-length if available
+    const contentLength = response.headers.get('content-length')
+    if (contentLength && parseInt(contentLength, 10) > MAX_DOWNLOAD_SIZE_BYTES) {
+      logForDebugging(`Image too large (${contentLength} bytes): ${url}`)
+      return null
+    }
+
+    const contentType = response.headers.get('content-type') ?? ''
+    const format = detectFormat(url, contentType)
+
+    // Stream the response with a size limit
+    const reader = response.body?.getReader()
+    if (!reader) {
+      return null
+    }
+
+    const chunks: Uint8Array[] = []
+    let totalSize = 0
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      totalSize += value.byteLength
+      if (totalSize > MAX_DOWNLOAD_SIZE_BYTES) {
+        logForDebugging(`Image download exceeded size limit: ${url}`)
+        reader.cancel()
+        return null
+      }
+      chunks.push(value)
+    }
+
+    // Combine chunks
+    const combinedLength = chunks.reduce((acc, c) => acc + c.byteLength, 0)
+    const combined = new Uint8Array(combinedLength)
+    let offset = 0
+    for (const chunk of chunks) {
+      combined.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+
+    const buffer = Buffer.from(combined.buffer)
+
+    // Cache to disk
+    try {
+      await ensureUrlCacheDir()
+      const ext = format
+      const cachePath = join(getUrlCacheDir(), `${hashUrl(url)}.${ext}`)
+      const fh = await open(cachePath, 'w', 0o600)
+      try {
+        await fh.writeFile(buffer)
+        await fh.datasync()
+      } finally {
+        await fh.close()
+      }
+
+      const result: CachedImage = {
+        buffer,
+        format,
+        mediaType: formatToMediaType(format),
+        path: cachePath,
+      }
+
+      // Store in memory cache
+      evictOldestIfAtCap()
+      urlImageCache.set(url, result)
+
+      logForDebugging(`Cached image: ${url} -> ${cachePath}`)
+      return result
+    } catch (cacheError) {
+      // Cache write failed, still return the buffer
+      logForDebugging(`Failed to cache image to disk: ${cacheError}`)
+      return {
+        buffer,
+        format,
+        mediaType: formatToMediaType(format),
+        path: '',
+      }
+    }
+  } catch (error) {
+    logForDebugging(`Image download error: ${error}`)
+    return null
+  }
+}
+
+/**
+ * Read directory contents safely (returns empty array on error).
+ */
+async function readdirSafe(dir: string): Promise<string[]> {
+  try {
+    const { readdir } = await import('fs/promises')
+    const entries = await readdir(dir, { withFileTypes: false })
+    return entries as string[]
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Evict oldest in-memory cache entry if at capacity.
+ */
+function evictOldestIfAtCap(): void {
+  while (urlImageCache.size >= MAX_URL_CACHED_IMAGES) {
+    const oldest = urlImageCache.keys().next().value
+    if (oldest !== undefined) {
+      urlImageCache.delete(oldest)
+    } else {
+      break
+    }
+  }
+}
+
+/**
+ * Clear the in-memory URL image cache.
+ */
+export function clearUrlImageCache(): void {
+  urlImageCache.clear()
+}

src/utils/markdown.ts

@@ -137,6 +137,8 @@ export function formatToken(
     case 'hr':
       return '---'
     case 'image':
+      // Fallback: Markdown.tsx intercepts image tokens to render <InlineImage>,
+      // but if formatToken is called directly (e.g. from applyMarkdown), show URL.
       return token.href
     case 'link': {
       // Prevent mailto links from being displayed as clickable links
@@ -286,6 +288,14 @@ export function formatToken(
 // only) so hostnames like docs.github.io/guide#42 don't false-positive. Repo
 // segment allows dots (e.g. cc.kurs.web). Lookbehind is avoided — it defeats
 // YARR JIT in JSC.
+/**
+ * Regex for detecting bare image URLs in text.
+ * Matches URLs ending in common image extensions.
+ * Used by Markdown.tsx to split text tokens containing image URLs.
+ */
+export const IMAGE_URL_RE =
+  /https?:\/\/[^\s()<>]+?\.(?:png|jpg|jpeg|gif|webp)(?:[?#][^\s()<>]*?)?/gi
+
 const ISSUE_REF_PATTERN =
   /(^|[^\w./-])([A-Za-z0-9][\w-]*\/[A-Za-z0-9][\w.-]*)#(\d+)\b/g
 

src/utils/terminalImage.ts

@@ -0,0 +1,205 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { Buffer } from 'buffer'
+import { env } from './env.js'
+import { execFileNoThrow } from './execFileNoThrow.js'
+import { wrapForMultiplexer } from '../ink/termio/osc.js'
+import { which } from './which.js'
+
+export type ImageProtocol = 'kitty' | null
+
+/** Is the terminal inside tmux? */
+export function isInsideTmux(): boolean {
+  return !!process.env.TMUX
+}
+
+const KITTY_IMAGE_CHUNK_SIZE = 4096
+
+// Image format codes for Kitty protocol
+const KITTY_FORMAT_CODES: Record<string, number> = {
+  png: 100,
+  jpeg: 101,
+  jpg: 101,
+  gif: 102,
+  webp: 103,
+}
+
+/**
+ * Detect whether the current terminal supports inline image display via
+ * the Kitty graphics protocol. Kitty, WezTerm, Konsole, foot, and
+ * Ghostty all support it.
+ */
+export function supportsImageProtocol(): boolean {
+  return detectImageProtocol() !== null
+}
+
+/**
+ * Detect the best available terminal image protocol.
+ * Currently only supports the Kitty protocol.
+ *
+ * Returns `'kitty'` or `null` if no protocol is available.
+ */
+export function detectImageProtocol(): ImageProtocol {
+  const term = env.terminal ?? ''
+
+  // Explicit TERM check for Kitty (TERM=xterm-kitty or TERM contains kitty)
+  if (process.env.TERM?.includes('kitty')) return 'kitty'
+  if (process.env.KITTY_WINDOW_ID) return 'kitty'
+
+  // TERM_PROGRAM-based detection
+  switch (term) {
+    case 'kitty':
+    case 'WezTerm':
+    case 'konsole':
+    case 'ghostty':
+    case 'foot':
+      return 'kitty'
+  }
+
+  return null
+}
+
+/**
+ * Get the Kitty protocol format code for a given image format string.
+ * Defaults to PNG (100) for unknown formats.
+ */
+function getKittyFormatCode(format: string): number {
+  return KITTY_FORMAT_CODES[format.toLowerCase()] ?? 100
+}
+
+/**
+ * Encode an image buffer into Kitty graphics protocol escape sequences.
+ *
+ * Large images are split into chunks of KITTY_IMAGE_CHUNK_SIZE bytes
+ * to avoid overflowing terminal input buffers.
+ *
+ * @param buffer - Raw image data
+ * @param format - Image format (png, jpeg, gif, webp)
+ * @returns Kitty protocol escape sequence
+ */
+export function encodeKittyImage(buffer: Buffer, format: string): string {
+  const f = getKittyFormatCode(format)
+  const b64 = buffer.toString('base64')
+  const parts: string[] = []
+
+  if (b64.length <= KITTY_IMAGE_CHUNK_SIZE) {
+    // Single chunk — no splitting needed
+    parts.push(`\x1b_Ga=d,f=${f},m=0;${b64}\x1b\\`)
+  } else {
+    // Split into multiple chunks
+    let offset = 0
+    while (offset < b64.length) {
+      const chunk = b64.slice(offset, offset + KITTY_IMAGE_CHUNK_SIZE)
+      const isLast = offset + KITTY_IMAGE_CHUNK_SIZE >= b64.length
+      parts.push(`\x1b_Ga=d,f=${f},m=${isLast ? 0 : 1};${chunk}\x1b\\`)
+      offset += KITTY_IMAGE_CHUNK_SIZE
+    }
+  }
+
+  const sequence = parts.join('')
+
+  // Wrap for tmux/screen multiplexer passthrough if needed
+  return wrapForMultiplexer(sequence)
+}
+
+/**
+ * Generate a terminal image display sequence for an image buffer.
+ * Picks the best protocol for the current terminal.
+ *
+ * @param buffer - Raw image data
+ * @param format - Image format (png, jpeg, gif, webp)
+ * @returns The escape sequence to write to stdout, or null if no protocol available
+ */
+export function encodeImageForTerminal(
+  buffer: Buffer,
+  format: string,
+): string | null {
+  const protocol = detectImageProtocol()
+  if (protocol === 'kitty') {
+    return encodeKittyImage(buffer, format)
+  }
+  return null
+}
+
+/**
+ * Image protocol capabilities summary (for debugging/logging).
+ */
+export function getImageProtocolSummary(): string {
+  const protocol = detectImageProtocol()
+  if (protocol === 'kitty') return 'kitty'
+  return 'none'
+}
+
+/**
+ * Render an image using the `timg` utility with Unicode block characters.
+ * Works in any terminal that supports Unicode and 24-bit color (virtually all
+ * modern terminals). Falls back gracefully if timg is not installed.
+ *
+ * The image is rendered using quarter-block characters ("pixelation q") for
+ * the best quality-to-compatibility ratio. If timg fails, half-blocks are
+ * tried as a fallback.
+ *
+ * @param buffer - The raw image buffer (decoded)
+ * @param format - Image format (png, jpeg, gif, webp)
+ * @param columns - Optional terminal width in character columns (auto-detected)
+ * @param rows - Optional terminal height in character rows (auto-detected)
+ * @returns ANSI escape sequence string for rendering, or null on failure
+ */
+export async function renderImageWithTimg(
+  buffer: Buffer,
+  format: string,
+  columns?: number,
+  rows?: number,
+): Promise<string | null> {
+  try {
+    const timgPath = await which('timg')
+    if (!timgPath) return null
+
+    const cols = columns ?? process.stdout.columns ?? 80
+    const termRows = rows ?? process.stdout.rows ?? 40
+    const tmpDir = mkdtempSync(join(tmpdir(), 'versperclaw-timg-'))
+    const ext = format === 'jpeg' ? 'jpg' : format
+    const tmpFile = join(tmpDir, `image.${ext}`)
+    let result: string | null = null
+
+    // Use at most half the terminal height so the image doesn't dominate
+    const maxRows = Math.max(10, Math.floor(termRows * 0.5))
+
+    try {
+      writeFileSync(tmpFile, buffer)
+
+      // Try quarter blocks first (4 pixels per cell, better quality)
+      const quarter = await execFileNoThrow(
+        timgPath,
+        ['-p', 'q', '-g', `${cols}x${maxRows}`, tmpFile],
+        { timeout: 15000, preserveOutputOnError: true },
+      )
+      if (quarter.code === 0 && quarter.stdout) {
+        result = quarter.stdout
+      }
+
+      // Fallback to half blocks (2 pixels per cell, max compatibility)
+      if (!result) {
+        const half = await execFileNoThrow(
+          timgPath,
+          ['-p', 'h', '-g', `${cols}x${maxRows}`, tmpFile],
+          { timeout: 15000, preserveOutputOnError: true },
+        )
+        if (half.code === 0 && half.stdout) {
+          result = half.stdout
+        }
+      }
+    } finally {
+      try {
+        rmSync(tmpDir, { recursive: true, force: true })
+      } catch {
+        // ignore cleanup errors
+      }
+    }
+
+    return result
+  } catch {
+    return null
+  }
+}