feat: ai friend companion on desktop

desktop/src/components/companion/CompanionControls.tsx

@@ -0,0 +1,113 @@
+import { useTranslation } from '../../i18n'
+import type { CompanionStatus } from '../../types/companion'
+
+interface CompanionControlsProps {
+  status: CompanionStatus
+  micEnabled: boolean
+  cameraEnabled: boolean
+  generating: boolean
+  onToggleMic: () => void
+  onToggleCamera: () => void
+  onConnect: () => void
+  onDisconnect: () => void
+  onStop: () => void
+  onResumeAudio: () => void
+}
+
+export function CompanionControls({
+  status,
+  micEnabled,
+  cameraEnabled,
+  generating,
+  onToggleMic,
+  onToggleCamera,
+  onConnect,
+  onDisconnect,
+  onStop,
+  onResumeAudio,
+}: CompanionControlsProps) {
+  const t = useTranslation()
+  const isConnected = status === 'connected'
+
+  return (
+    <div className="companion-controls absolute bottom-4 left-1/2 -translate-x-1/2 flex items-center gap-3 px-6 py-3 rounded-2xl bg-black/50 backdrop-blur-md border border-white/10">
+      {/* Mic toggle */}
+      <button
+        type="button"
+        onClick={onToggleMic}
+        disabled={!isConnected}
+        className={`flex h-10 w-10 items-center justify-center rounded-xl transition-all ${
+          micEnabled
+            ? 'bg-white/10 text-white hover:bg-white/20'
+            : 'bg-red-500/20 text-red-400'
+        } disabled:opacity-40`}
+        title={micEnabled ? t('companion.micOn') : t('companion.micOff')}
+      >
+        <span className="material-symbols-outlined text-xl">
+          {micEnabled ? 'mic' : 'mic_off'}
+        </span>
+      </button>
+
+      {/* Camera toggle */}
+      <button
+        type="button"
+        onClick={onToggleCamera}
+        disabled={!isConnected}
+        className={`flex h-10 w-10 items-center justify-center rounded-xl transition-all ${
+          cameraEnabled
+            ? 'bg-white/10 text-white hover:bg-white/20'
+            : 'bg-red-500/20 text-red-400'
+        } disabled:opacity-40`}
+        title={cameraEnabled ? t('companion.cameraOn') : t('companion.cameraOff')}
+      >
+        <span className="material-symbols-outlined text-xl">
+          {cameraEnabled ? 'videocam' : 'videocam_off'}
+        </span>
+      </button>
+
+      <div className="w-px h-8 bg-white/10" />
+
+      {/* Stop generation */}
+      {generating && (
+        <button
+          type="button"
+          onClick={onStop}
+          className="flex h-10 w-10 items-center justify-center rounded-xl bg-red-500/30 text-red-400 hover:bg-red-500/50 transition-all"
+          title="Stop"
+        >
+          <span className="material-symbols-outlined text-xl">stop</span>
+        </button>
+      )}
+
+      {/* Connect / Disconnect */}
+      {isConnected ? (
+        <button
+          type="button"
+          onClick={() => {
+            onDisconnect()
+          }}
+          className="flex h-10 items-center gap-2 rounded-xl bg-red-500/20 px-4 text-red-400 hover:bg-red-500/30 transition-all text-sm font-medium"
+        >
+          <span className="material-symbols-outlined text-lg">link_off</span>
+          {t('companion.disconnect')}
+        </button>
+      ) : (
+        <button
+          type="button"
+          onClick={() => {
+            onConnect()
+            // Resume audio context on user gesture
+            onResumeAudio()
+          }}
+          disabled={status === 'connecting'}
+          className="flex h-10 items-center gap-2 rounded-xl bg-purple-600/30 px-4 text-purple-300 hover:bg-purple-600/50 transition-all text-sm font-medium disabled:opacity-40"
+        >
+          <span className="material-symbols-outlined text-lg">
+            {status === 'connecting' ? 'hourglass_top' : 'link'}
+          </span>
+          {status === 'connecting' ? t('companion.status.connecting') : t('companion.connect')}
+        </button>
+      )}
+    </div>
+  )
+}

desktop/src/components/companion/CompanionTranscript.tsx

@@ -0,0 +1,84 @@
+import { useRef, useEffect, useState, useCallback } from 'react'
+import { useTranslation } from '../../i18n'
+
+interface CompanionTranscriptProps {
+  transcript: string
+  fullTranscript: string
+  onSendText: (text: string) => void
+  disabled?: boolean
+}
+
+export function CompanionTranscript({ transcript, fullTranscript, onSendText, disabled }: CompanionTranscriptProps) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const [inputValue, setInputValue] = useState('')
+  const t = useTranslation()
+
+  useEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight
+    }
+  }, [transcript, fullTranscript])
+
+  const handleSend = useCallback(() => {
+    const text = inputValue.trim()
+    if (!text) return
+    onSendText(text)
+    setInputValue('')
+  }, [inputValue, onSendText])
+
+  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      handleSend()
+    }
+  }, [handleSend])
+
+  return (
+    <div className="companion-transcript absolute bottom-20 left-1/2 -translate-x-1/2 w-full max-w-2xl px-4">
+      {/* Transcript display */}
+      <div
+        ref={scrollRef}
+        className="max-h-[150px] overflow-y-auto rounded-2xl bg-black/40 backdrop-blur-md border border-white/10 p-4 mb-2 scrollbar-thin"
+      >
+        {fullTranscript && (
+          <div className="text-white/40 text-xs mb-2 whitespace-pre-wrap leading-relaxed">
+            {fullTranscript}
+          </div>
+        )}
+        {transcript && (
+          <div className="text-white/90 text-sm font-medium leading-relaxed">
+            {transcript}
+            <span className="inline-block w-1.5 h-4 ml-0.5 bg-purple-400 animate-pulse" />
+          </div>
+        )}
+        {!transcript && !fullTranscript && (
+          <div className="text-white/30 text-sm text-center py-2">
+            {t('companion.transcriptPlaceholder')}
+          </div>
+        )}
+      </div>
+
+      {/* Text input row */}
+      <div className="flex items-center gap-2 rounded-2xl bg-black/40 backdrop-blur-md border border-white/10 px-4 py-2">
+        <input
+          type="text"
+          value={inputValue}
+          onChange={(e) => setInputValue(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder={t('companion.inputPlaceholder')}
+          disabled={disabled}
+          className="flex-1 bg-transparent text-sm text-white/90 placeholder-white/30 outline-none border-none disabled:opacity-40"
+        />
+        <button
+          type="button"
+          onClick={handleSend}
+          disabled={disabled || !inputValue.trim()}
+          className="flex h-8 w-8 items-center justify-center rounded-lg bg-purple-600/40 text-purple-300 hover:bg-purple-600/60 transition-all disabled:opacity-30"
+          title={t('companion.send')}
+        >
+          <span className="material-symbols-outlined text-lg">send</span>
+        </button>
+      </div>
+    </div>
+  )
+}

desktop/src/components/companion/CompanionVideoPanel.tsx

@@ -0,0 +1,94 @@
+import { useEffect, useRef } from 'react'
+import { useTranslation } from '../../i18n'
+import type { CompanionStatus } from '../../types/companion'
+
+interface CompanionVideoPanelProps {
+  webcamStream: MediaStream | null
+  speaking: boolean
+  generating: boolean
+  status: CompanionStatus
+}
+
+export function CompanionVideoPanel({
+  webcamStream,
+  speaking,
+  generating,
+  status,
+}: CompanionVideoPanelProps) {
+  const videoRef = useRef<HTMLVideoElement>(null)
+  const t = useTranslation()
+
+  useEffect(() => {
+    if (videoRef.current && webcamStream) {
+      videoRef.current.srcObject = webcamStream
+    }
+  }, [webcamStream])
+
+  const statusLabel = generating
+    ? t('companion.speaking')
+    : speaking
+    ? t('companion.listening')
+    : status === 'connected'
+    ? t('companion.alwaysHere')
+    : t('companion.status.disconnected')
+
+  return (
+    <div className="companion-video-panel absolute inset-0 overflow-hidden">
+      {/* Background gradient */}
+      <div
+        className={`absolute inset-0 transition-all duration-700 ${
+          generating
+            ? 'bg-gradient-to-br from-indigo-950 via-purple-900 to-slate-950'
+            : 'bg-gradient-to-br from-slate-900 via-slate-800 to-slate-900'
+        }`}
+      />
+
+      {/* AI Presence indicator */}
+      <div className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 flex flex-col items-center gap-4">
+        <div
+          className={`w-32 h-32 rounded-full transition-all duration-500 flex items-center justify-center ${
+            generating
+              ? 'bg-purple-600/30 shadow-[0_0_60px_rgba(147,51,234,0.4)] animate-pulse'
+              : speaking
+              ? 'bg-blue-500/20 shadow-[0_0_30px_rgba(59,130,246,0.3)]'
+              : 'bg-gray-600/10'
+          }`}
+        >
+          <span className="material-symbols-outlined text-5xl text-white/60">
+            {generating ? 'record_voice_over' : 'psychology'}
+          </span>
+        </div>
+        <span className="text-white/40 text-sm font-medium">{statusLabel}</span>
+      </div>
+
+      {/* Webcam PiP overlay */}
+      {webcamStream && (
+        <div className="absolute bottom-6 right-6 w-[180px] h-[240px] rounded-2xl overflow-hidden border-2 border-white/20 shadow-2xl bg-black">
+          <video
+            ref={videoRef}
+            autoPlay
+            muted
+            playsInline
+            className="h-full w-full object-cover scale-x-[-1]"
+          />
+        </div>
+      )}
+
+      {/* Connection status badge */}
+      <div className="absolute top-4 right-4 flex items-center gap-2 px-3 py-1.5 rounded-full bg-black/40 backdrop-blur-sm">
+        <span
+          className={`w-2 h-2 rounded-full ${
+            status === 'connected'
+              ? 'bg-green-500'
+              : status === 'connecting'
+              ? 'bg-yellow-500 animate-pulse'
+              : status === 'error'
+              ? 'bg-red-500'
+              : 'bg-gray-500'
+          }`}
+        />
+        <span className="text-white/60 text-xs">{status}</span>
+      </div>
+    </div>
+  )
+}

desktop/src/components/layout/ContentRouter.tsx

@@ -5,6 +5,7 @@ import { ActiveSession } from '../../pages/ActiveSession'
 import { ScheduledTasks } from '../../pages/ScheduledTasks'
 import { Settings } from '../../pages/Settings'
 import { TerminalSettings } from '../../pages/TerminalSettings'
+import { Companion } from '../../pages/Companion'
 
 export function ContentRouter() {
   const activeTabId = useTabStore((s) => s.activeTabId)
@@ -19,6 +20,8 @@ export function ContentRouter() {
     page = <Settings />
   } else if (activeTabType === 'scheduled') {
     page = <ScheduledTasks />
+  } else if (activeTabType === 'companion') {
+    page = <Companion />
   } else if (activeTabType !== 'terminal') {
     page = <ActiveSession />
   }

desktop/src/components/layout/Sidebar.tsx

@@ -5,7 +5,7 @@ import { useUIStore } from '../../stores/uiStore'
 import { useTranslation, type TranslationKey } from '../../i18n'
 import { ConfirmDialog } from '../shared/ConfirmDialog'
 import type { SessionListItem } from '../../types/session'
-import { useTabStore, SETTINGS_TAB_ID, SCHEDULED_TAB_ID } from '../../stores/tabStore'
+import { useTabStore, SETTINGS_TAB_ID, SCHEDULED_TAB_ID, COMPANION_TAB_ID } from '../../stores/tabStore'
 import { useChatStore } from '../../stores/chatStore'
 import { useOpenTargetStore } from '../../stores/openTargetStore'
 import { desktopUiPreferencesApi, type SidebarProjectPreferences } from '../../api/desktopUiPreferences'
@@ -698,6 +698,21 @@ export function Sidebar({ isMobile = false, onRequestClose }: SidebarProps) {
             {t('sidebar.scheduled')}
           </NavItem>
         )}
+        {!isMobile && (
+          <NavItem
+            active={activeTabId === COMPANION_TAB_ID}
+            collapsed={!expanded}
+            label={t('sidebar.companion')}
+            touchFriendly={isMobile}
+            onClick={() => {
+              useTabStore.getState().openTab(COMPANION_TAB_ID, t('sidebar.companion'), 'companion')
+              closeMobileDrawer()
+            }}
+            icon={<span className="material-symbols-outlined text-[18px]">videocam</span>}
+          >
+            {t('sidebar.companion')}
+          </NavItem>
+        )}
       </div>
 
       {expanded ? (

desktop/src/hooks/useCompanionAudio.ts

@@ -0,0 +1,145 @@
+import { useRef, useCallback, useEffect } from 'react'
+
+function pcmToWav(pcm: ArrayBuffer): Blob {
+  const int16 = new Int16Array(pcm)
+  const numSamples = int16.length
+  const sampleRate = 24000
+  const numChannels = 1
+  const bitsPerSample = 16
+  const byteRate = (sampleRate * numChannels * bitsPerSample) / 8
+  const blockAlign = (numChannels * bitsPerSample) / 8
+  const dataSize = numSamples * blockAlign
+  const headerSize = 44
+  const totalSize = headerSize + dataSize
+
+  const buf = new ArrayBuffer(totalSize)
+  const view = new DataView(buf)
+
+  const w = (offset: number, str: string) => {
+    for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i))
+  }
+
+  w(0, 'RIFF')
+  view.setUint32(4, totalSize - 8, true)
+  w(8, 'WAVE')
+  w(12, 'fmt ')
+  view.setUint32(16, 16, true)
+  view.setUint16(20, 1, true) // PCM
+  view.setUint16(22, numChannels, true)
+  view.setUint32(24, sampleRate, true)
+  view.setUint32(28, byteRate, true)
+  view.setUint16(32, blockAlign, true)
+  view.setUint16(34, bitsPerSample, true)
+  w(36, 'data')
+  view.setUint32(40, dataSize, true)
+
+  new Int16Array(buf, headerSize, numSamples).set(int16)
+  return new Blob([buf], { type: 'audio/wav' })
+}
+
+export function useCompanionAudio() {
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  const queueRef = useRef<Blob[]>([])
+  const playingRef = useRef(false)
+  const urlRef = useRef<string | null>(null)
+
+  const revokeUrl = useCallback(() => {
+    if (urlRef.current) {
+      URL.revokeObjectURL(urlRef.current)
+      urlRef.current = null
+    }
+  }, [])
+
+  const playNext = useCallback(() => {
+    if (playingRef.current) return
+    const queue = queueRef.current
+    if (queue.length === 0) return
+
+    const blob = queue.shift()!
+    const url = URL.createObjectURL(blob)
+    const audio = audioRef.current
+    if (!audio) return
+
+    revokeUrl()
+    urlRef.current = url
+    audio.src = url
+    audio.play().then(() => {
+      playingRef.current = true
+    }).catch(() => {
+      playingRef.current = false
+      revokeUrl()
+      playNext()
+    })
+  }, [revokeUrl])
+
+  useEffect(() => {
+    const audio = new Audio()
+    audioRef.current = audio
+    audio.style.display = 'none'
+    document.body.appendChild(audio)
+
+    audio.onended = () => {
+      playingRef.current = false
+      playNext()
+    }
+    audio.onerror = () => {
+      playingRef.current = false
+      playNext()
+    }
+
+    return () => {
+      audio.pause()
+      revokeUrl()
+      audio.src = ''
+      if (audio.parentNode) {
+        audio.parentNode.removeChild(audio)
+      }
+      audioRef.current = null
+      queueRef.current = []
+      playingRef.current = false
+    }
+  }, [revokeUrl])
+
+  const enqueueAudio = useCallback(
+    (pcmData: ArrayBuffer) => {
+      const wav = pcmToWav(pcmData)
+      queueRef.current.push(wav)
+      if (!playingRef.current) {
+        playNext()
+      }
+    },
+    [playNext],
+  )
+
+  const stopPlayback = useCallback(() => {
+    const audio = audioRef.current
+    if (audio) {
+      audio.pause()
+      revokeUrl()
+      audio.src = ''
+    }
+    queueRef.current = []
+    playingRef.current = false
+  }, [revokeUrl])
+
+  const resume = useCallback(() => {
+    const audio = audioRef.current
+    if (!audio) return
+
+    // Unlock audio with a silent WAV
+    const silent = new Int16Array(1)
+    silent[0] = 0
+    const wav = pcmToWav(silent.buffer)
+    const url = URL.createObjectURL(wav)
+    revokeUrl()
+    urlRef.current = url
+    audio.src = url
+    audio.play().catch(() => {})
+  }, [revokeUrl])
+
+  return {
+    enqueueAudio,
+    stopPlayback,
+    resume,
+  }
+}

desktop/src/hooks/useCompanionWebSocket.ts

@@ -0,0 +1,162 @@
+import { useRef, useCallback, useEffect } from 'react'
+import { useCompanionStore } from '../stores/companionStore'
+
+interface Callbacks {
+  onAudioReceived: (data: ArrayBuffer) => void
+}
+
+export function useCompanionWebSocket(callbacks: Callbacks) {
+  const wsRef = useRef<WebSocket | null>(null)
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const reconnectAttemptRef = useRef(0)
+  const callbacksRef = useRef(callbacks)
+  const manualDisconnectRef = useRef(false)
+  const serverUrl = useCompanionStore((s) => s.serverUrl)
+  const status = useCompanionStore((s) => s.status)
+  const setStatus = useCompanionStore((s) => s.setStatus)
+  const setSpeaking = useCompanionStore((s) => s.setSpeaking)
+  const setGenerating = useCompanionStore((s) => s.setGenerating)
+  const appendTranscript = useCompanionStore((s) => s.appendTranscript)
+  const appendFullTranscript = useCompanionStore((s) => s.appendFullTranscript)
+  const resetTranscript = useCompanionStore((s) => s.resetTranscript)
+  const setError = useCompanionStore((s) => s.setError)
+
+  // Keep callbacks ref current
+  callbacksRef.current = callbacks
+
+  const cleanup = useCallback(() => {
+    if (reconnectTimerRef.current) {
+      clearTimeout(reconnectTimerRef.current)
+      reconnectTimerRef.current = null
+    }
+    if (wsRef.current) {
+      wsRef.current.onopen = null
+      wsRef.current.onclose = null
+      wsRef.current.onmessage = null
+      wsRef.current.onerror = null
+      wsRef.current.close()
+      wsRef.current = null
+    }
+  }, [])
+
+  const connect = useCallback(() => {
+    manualDisconnectRef.current = false
+    if (wsRef.current && (wsRef.current.readyState === WebSocket.OPEN || wsRef.current.readyState === WebSocket.CONNECTING)) {
+      return
+    }
+
+    cleanup()
+    setStatus('connecting')
+    setError(null)
+    resetTranscript()
+    reconnectAttemptRef.current = 0
+
+    const ws = new WebSocket(serverUrl)
+    ws.binaryType = 'arraybuffer'
+    wsRef.current = ws
+
+    ws.onopen = () => {
+      reconnectAttemptRef.current = 0
+      setStatus('connected')
+    }
+
+    ws.onclose = () => {
+      if (!manualDisconnectRef.current) {
+        // Auto reconnect with exponential backoff
+        const attempt = reconnectAttemptRef.current
+        const delay = Math.min(1000 * Math.pow(2, attempt), 30000)
+        reconnectAttemptRef.current = attempt + 1
+        reconnectTimerRef.current = setTimeout(() => {
+          connect()
+        }, delay)
+      }
+      setStatus('disconnected')
+    }
+
+    ws.onerror = () => {
+      setError('WebSocket connection error')
+    }
+
+    ws.onmessage = (event) => {
+      if (event.data instanceof ArrayBuffer) {
+        // Binary frame = PCM audio
+        callbacksRef.current.onAudioReceived(event.data)
+      } else {
+        // Text frame = JSON control message
+        try {
+          const msg = JSON.parse(event.data)
+          switch (msg.type) {
+            case 'vad':
+              setSpeaking(msg.speaking)
+              break
+            case 'generating':
+              setGenerating(true)
+              resetTranscript()
+              break
+            case 'text':
+              appendTranscript(msg.content)
+              break
+            case 'done':
+              appendFullTranscript(
+                useCompanionStore.getState().transcript
+              )
+              setGenerating(false)
+              setSpeaking(false)
+              break
+          }
+        } catch {
+          // Ignore malformed messages
+        }
+      }
+    }
+  }, [serverUrl, cleanup, setStatus, setError, resetTranscript, setSpeaking, setGenerating, appendTranscript, appendFullTranscript])
+
+  const disconnect = useCallback(() => {
+    manualDisconnectRef.current = true
+    cleanup()
+    setStatus('disconnected')
+    setError(null)
+  }, [cleanup, setStatus])
+
+  const sendFrame = useCallback((base64Jpeg: string) => {
+    if (wsRef.current?.readyState === WebSocket.OPEN) {
+      wsRef.current.send(JSON.stringify({ type: 'frame', data: base64Jpeg }))
+    }
+  }, [])
+
+  const sendAudio = useCallback((buffer: ArrayBuffer) => {
+    if (wsRef.current?.readyState === WebSocket.OPEN) {
+      wsRef.current.send(buffer)
+    }
+  }, [])
+
+  const sendStop = useCallback(() => {
+    if (wsRef.current?.readyState === WebSocket.OPEN) {
+      wsRef.current.send(JSON.stringify({ type: 'stop' }))
+    }
+  }, [])
+
+  const sendText = useCallback((text: string) => {
+    if (wsRef.current?.readyState === WebSocket.OPEN) {
+      wsRef.current.send(JSON.stringify({ type: 'text', content: text }))
+    }
+  }, [])
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      manualDisconnectRef.current = true
+      cleanup()
+    }
+  }, [cleanup])
+
+  return {
+    connect,
+    disconnect,
+    sendFrame,
+    sendAudio,
+    sendStop,
+    sendText,
+    connected: status === 'connected',
+  }
+}

desktop/src/hooks/useMicrophone.ts

@@ -0,0 +1,96 @@
+import { useState, useRef, useCallback, useEffect } from 'react'
+
+export function useMicrophone(
+  enabled: boolean,
+  onAudioChunk: (buffer: ArrayBuffer) => void,
+) {
+  const [stream, setStream] = useState<MediaStream | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const streamRef = useRef<MediaStream | null>(null)
+  const audioContextRef = useRef<AudioContext | null>(null)
+  const processorRef = useRef<ScriptProcessorNode | null>(null)
+  const sourceRef = useRef<MediaStreamAudioSourceNode | null>(null)
+
+  const startMic = useCallback(async () => {
+    try {
+      const mediaStream = await navigator.mediaDevices.getUserMedia({
+        audio: {
+          echoCancellation: true,
+          noiseSuppression: true,
+          sampleRate: { ideal: 16000 },
+        },
+      })
+      streamRef.current = mediaStream
+      setStream(mediaStream)
+      setError(null)
+
+      // Set up audio processing pipeline
+      const audioContext = new AudioContext({ sampleRate: 16000 })
+      audioContextRef.current = audioContext
+
+      const source = audioContext.createMediaStreamSource(mediaStream)
+      sourceRef.current = source
+
+      // Use ScriptProcessorNode for PCM data access
+      const bufferSize = 2048
+      const processor = audioContext.createScriptProcessor(bufferSize, 1, 1)
+      processorRef.current = processor
+
+      processor.onaudioprocess = (event) => {
+        const inputData = event.inputBuffer.getChannelData(0) // Float32
+        // Convert Float32 to Int16 PCM
+        const int16 = new Int16Array(inputData.length)
+        for (let i = 0; i < inputData.length; i++) {
+          const sample = inputData[i] ?? 0
+          const s = Math.max(-1, Math.min(1, sample))
+          int16[i] = s < 0 ? s * 0x8000 : s * 0x7fff
+        }
+        onAudioChunk(int16.buffer)
+      }
+
+      source.connect(processor)
+      processor.connect(audioContext.destination)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      setError(`Microphone access denied: ${message}`)
+    }
+  }, [onAudioChunk])
+
+  const stopMic = useCallback(() => {
+    if (processorRef.current) {
+      processorRef.current.disconnect()
+      processorRef.current = null
+    }
+    if (sourceRef.current) {
+      sourceRef.current.disconnect()
+      sourceRef.current = null
+    }
+    if (audioContextRef.current) {
+      void audioContextRef.current.close()
+      audioContextRef.current = null
+    }
+    if (streamRef.current) {
+      streamRef.current.getTracks().forEach((track) => track.stop())
+      streamRef.current = null
+    }
+    setStream(null)
+  }, [])
+
+  useEffect(() => {
+    if (enabled) {
+      void startMic()
+    } else {
+      stopMic()
+    }
+    return () => {
+      stopMic()
+    }
+  }, [enabled, startMic, stopMic])
+
+  return {
+    stream,
+    error,
+    startMic,
+    stopMic,
+  }
+}

desktop/src/hooks/useWebcam.ts

@@ -0,0 +1,103 @@
+import { useState, useRef, useCallback, useEffect } from 'react'
+
+export function useWebcam(enabled: boolean) {
+  const [stream, setStream] = useState<MediaStream | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const streamRef = useRef<MediaStream | null>(null)
+  const videoRef = useRef<HTMLVideoElement | null>(null)
+  const canvasRef = useRef<HTMLCanvasElement | null>(null)
+
+  const startCamera = useCallback(async () => {
+    try {
+      const mediaStream = await navigator.mediaDevices.getUserMedia({
+        video: {
+          width: { ideal: 640 },
+          height: { ideal: 480 },
+          facingMode: 'user',
+        },
+      })
+      streamRef.current = mediaStream
+      setStream(mediaStream)
+      setError(null)
+
+      // Create hidden video and canvas elements for frame capture
+      const video = document.createElement('video')
+      video.srcObject = mediaStream
+      video.playsInline = true
+      video.muted = true
+      video.autoplay = true
+      videoRef.current = video
+
+      const canvas = document.createElement('canvas')
+      canvas.width = 256
+      canvas.height = 256
+      canvasRef.current = canvas
+
+      await video.play()
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      setError(`Camera access denied: ${message}`)
+    }
+  }, [])
+
+  const stopCamera = useCallback(() => {
+    if (streamRef.current) {
+      streamRef.current.getTracks().forEach((track) => track.stop())
+      streamRef.current = null
+    }
+    videoRef.current = null
+    canvasRef.current = null
+    setStream(null)
+  }, [])
+
+  const captureFrame = useCallback(async (): Promise<string | null> => {
+    const video = videoRef.current
+    const canvas = canvasRef.current
+    if (!video || !canvas || video.readyState < 2) return null
+
+    const ctx = canvas.getContext('2d')
+    if (!ctx) return null
+
+    ctx.drawImage(video, 0, 0, 256, 256)
+
+    return new Promise((resolve) => {
+      canvas.toBlob(
+        (blob) => {
+          if (!blob) {
+            resolve(null)
+            return
+          }
+          const reader = new FileReader()
+          reader.onloadend = () => {
+            const result = reader.result as string
+            // Remove data:image/jpeg;base64, prefix
+            resolve(result.split(',')[1] ?? null)
+          }
+          reader.onerror = () => resolve(null)
+          reader.readAsDataURL(blob)
+        },
+        'image/jpeg',
+        0.7,
+      )
+    })
+  }, [])
+
+  useEffect(() => {
+    if (enabled) {
+      void startCamera()
+    } else {
+      stopCamera()
+    }
+    return () => {
+      stopCamera()
+    }
+  }, [enabled, startCamera, stopCamera])
+
+  return {
+    stream,
+    error,
+    captureFrame,
+    startCamera,
+    stopCamera,
+  }
+}

desktop/src/i18n/locales/en.ts

@@ -58,6 +58,27 @@ export const en = {
   'sidebar.worktree': 'worktree',
   'sidebar.sessionRunning': 'Session running',
   'sidebar.missingDir': 'missing dir',
+  'sidebar.companion': 'AI Companion',
+
+  // ─── Companion ──────────────────────────────────────
+  'companion.connect': 'Connect',
+  'companion.disconnect': 'Disconnect',
+  'companion.micOn': 'Mute',
+  'companion.micOff': 'Unmute',
+  'companion.cameraOn': 'Turn Camera Off',
+  'companion.cameraOff': 'Turn Camera On',
+  'companion.status.connected': 'Connected',
+  'companion.status.disconnected': 'Disconnected',
+  'companion.status.connecting': 'Connecting...',
+  'companion.status.error': 'Connection Error',
+  'companion.transcriptPlaceholder': 'AI responses will appear here...',
+  'companion.serverUrl': 'Server URL',
+  'companion.voiceName': 'Voice',
+  'companion.alwaysHere': 'Always here',
+  'companion.listening': 'Listening...',
+  'companion.speaking': 'Speaking...',
+  'companion.inputPlaceholder': 'Type a message...',
+  'companion.send': 'Send',
   'sidebar.confirmDelete': 'Delete this session? This cannot be undone.',
   'sidebar.batchManage': 'Batch manage',
   'sidebar.batchSelectedCount': '{count} selected',

desktop/src/i18n/locales/zh.ts

@@ -60,6 +60,27 @@ export const zh: Record<TranslationKey, string> = {
   'sidebar.worktree': 'worktree',
   'sidebar.sessionRunning': '会话运行中',
   'sidebar.missingDir': '目录缺失',
+  'sidebar.companion': 'AI 伴侣',
+
+  // ─── Companion ──────────────────────────────────────
+  'companion.connect': '连接',
+  'companion.disconnect': '断开',
+  'companion.micOn': '静音',
+  'companion.micOff': '取消静音',
+  'companion.cameraOn': '关闭摄像头',
+  'companion.cameraOff': '打开摄像头',
+  'companion.status.connected': '已连接',
+  'companion.status.disconnected': '未连接',
+  'companion.status.connecting': '连接中...',
+  'companion.status.error': '连接错误',
+  'companion.transcriptPlaceholder': 'AI 回复将显示在这里...',
+  'companion.serverUrl': '服务器地址',
+  'companion.voiceName': '音色',
+  'companion.alwaysHere': '随时待命',
+  'companion.listening': '聆听中...',
+  'companion.speaking': '说话中...',
+  'companion.inputPlaceholder': '输入消息...',
+  'companion.send': '发送',
   'sidebar.confirmDelete': '确定要删除这个会话吗？此操作不可撤销。',
   'sidebar.batchManage': '批量管理',
   'sidebar.batchSelectedCount': '已选 {count} 个',

desktop/src/pages/Companion.tsx

@@ -0,0 +1,123 @@
+import { useEffect, useRef, useCallback } from 'react'
+import { useCompanionStore } from '../stores/companionStore'
+import { useCompanionWebSocket } from '../hooks/useCompanionWebSocket'
+import { useWebcam } from '../hooks/useWebcam'
+import { useMicrophone } from '../hooks/useMicrophone'
+import { useCompanionAudio } from '../hooks/useCompanionAudio'
+import { CompanionVideoPanel } from '../components/companion/CompanionVideoPanel'
+import { CompanionTranscript } from '../components/companion/CompanionTranscript'
+import { CompanionControls } from '../components/companion/CompanionControls'
+
+export function Companion() {
+  const status = useCompanionStore((s) => s.status)
+  const speaking = useCompanionStore((s) => s.speaking)
+  const generating = useCompanionStore((s) => s.generating)
+  const transcript = useCompanionStore((s) => s.transcript)
+  const fullTranscript = useCompanionStore((s) => s.fullTranscript)
+  const micEnabled = useCompanionStore((s) => s.micEnabled)
+  const cameraEnabled = useCompanionStore((s) => s.cameraEnabled)
+  const error = useCompanionStore((s) => s.error)
+  const setMicEnabled = useCompanionStore((s) => s.setMicEnabled)
+  const setCameraEnabled = useCompanionStore((s) => s.setCameraEnabled)
+  const reset = useCompanionStore((s) => s.reset)
+  const frameIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  const companionAudio = useCompanionAudio()
+  const onAudioReceived = useCallback(
+    (data: ArrayBuffer) => {
+      companionAudio.enqueueAudio(data)
+    },
+    [companionAudio],
+  )
+
+  const ws = useCompanionWebSocket({ onAudioReceived })
+  const webcam = useWebcam(ws.connected && cameraEnabled)
+  useMicrophone(ws.connected && micEnabled, ws.sendAudio)
+
+  // Periodic frame capture when connected and camera enabled
+  useEffect(() => {
+    if (ws.connected && cameraEnabled) {
+      frameIntervalRef.current = setInterval(async () => {
+        const frame = await webcam.captureFrame()
+        if (frame) {
+          ws.sendFrame(frame)
+        }
+      }, 1000)
+    } else {
+      if (frameIntervalRef.current) {
+        clearInterval(frameIntervalRef.current)
+        frameIntervalRef.current = null
+      }
+    }
+    return () => {
+      if (frameIntervalRef.current) {
+        clearInterval(frameIntervalRef.current)
+        frameIntervalRef.current = null
+      }
+    }
+  }, [ws.connected, cameraEnabled, webcam, ws])
+
+  const handleSendText = useCallback(
+    (text: string) => {
+      ws.sendText(text)
+    },
+    [ws],
+  )
+
+  // Resume audio context on user interaction
+  const handleResumeAudio = useCallback(() => {
+    companionAudio.resume()
+  }, [companionAudio])
+
+  const handleToggleMic = useCallback(() => {
+    setMicEnabled(!micEnabled)
+  }, [micEnabled, setMicEnabled])
+
+  const handleToggleCamera = useCallback(() => {
+    setCameraEnabled(!cameraEnabled)
+  }, [cameraEnabled, setCameraEnabled])
+
+  return (
+    <div className="relative h-full w-full overflow-hidden bg-black">
+      {/* Video background + PiP */}
+      <CompanionVideoPanel
+        webcamStream={webcam.stream}
+        speaking={speaking}
+        generating={generating}
+        status={status}
+      />
+
+      {/* Error overlay */}
+      {error && (
+        <div className="absolute top-4 left-1/2 -translate-x-1/2 px-4 py-2 rounded-xl bg-red-500/20 border border-red-500/30 text-red-300 text-sm">
+          {error}
+        </div>
+      )}
+
+      {/* Transcript + text input */}
+      <CompanionTranscript
+        transcript={transcript}
+        fullTranscript={fullTranscript}
+        onSendText={handleSendText}
+        disabled={status !== 'connected'}
+      />
+
+      {/* Controls */}
+      <CompanionControls
+        status={status}
+        micEnabled={micEnabled}
+        cameraEnabled={cameraEnabled}
+        generating={generating}
+        onToggleMic={handleToggleMic}
+        onToggleCamera={handleToggleCamera}
+        onConnect={ws.connect}
+        onDisconnect={() => {
+          ws.disconnect()
+          reset()
+        }}
+        onStop={ws.sendStop}
+        onResumeAudio={handleResumeAudio}
+      />
+    </div>
+  )
+}

desktop/src/stores/companionStore.ts

@@ -0,0 +1,65 @@
+import { create } from 'zustand'
+import type { CompanionStatus } from '../types/companion'
+
+interface CompanionStore {
+  status: CompanionStatus
+  serverUrl: string
+  voiceName: string
+  speaking: boolean
+  generating: boolean
+  transcript: string
+  fullTranscript: string
+  micEnabled: boolean
+  cameraEnabled: boolean
+  error: string | null
+
+  setServerUrl: (url: string) => void
+  setVoiceName: (name: string) => void
+  setStatus: (status: CompanionStatus) => void
+  setSpeaking: (speaking: boolean) => void
+  setGenerating: (generating: boolean) => void
+  appendTranscript: (text: string) => void
+  appendFullTranscript: (text: string) => void
+  resetTranscript: () => void
+  setMicEnabled: (enabled: boolean) => void
+  setCameraEnabled: (enabled: boolean) => void
+  setError: (error: string | null) => void
+  reset: () => void
+}
+
+const DEFAULT_SERVER_URL = 'ws://127.0.0.1:8889/ws/companion'
+
+export const useCompanionStore = create<CompanionStore>((set) => ({
+  status: 'disconnected',
+  serverUrl: DEFAULT_SERVER_URL,
+  voiceName: 'default',
+  speaking: false,
+  generating: false,
+  transcript: '',
+  fullTranscript: '',
+  micEnabled: true,
+  cameraEnabled: true,
+  error: null,
+
+  setServerUrl: (url) => set({ serverUrl: url }),
+  setVoiceName: (name) => set({ voiceName: name }),
+  setStatus: (status) => set({ status, error: status === 'error' ? undefined : null }),
+  setSpeaking: (speaking) => set({ speaking }),
+  setGenerating: (generating) => set({ generating }),
+  appendTranscript: (text) =>
+    set((s) => ({ transcript: s.transcript + text })),
+  appendFullTranscript: (text) =>
+    set((s) => ({ fullTranscript: s.fullTranscript + text + '\n' })),
+  resetTranscript: () => set({ transcript: '' }),
+  setMicEnabled: (enabled) => set({ micEnabled: enabled }),
+  setCameraEnabled: (enabled) => set({ cameraEnabled: enabled }),
+  setError: (error) => set({ error }),
+  reset: () =>
+    set({
+      status: 'disconnected',
+      speaking: false,
+      generating: false,
+      transcript: '',
+      error: null,
+    }),
+}))

desktop/src/stores/tabStore.ts

@@ -6,8 +6,9 @@ const TAB_STORAGE_KEY = 'cc-haha-open-tabs'
 export const SETTINGS_TAB_ID = '__settings__'
 export const SCHEDULED_TAB_ID = '__scheduled__'
 export const TERMINAL_TAB_PREFIX = '__terminal__'
+export const COMPANION_TAB_ID = '__companion__'
 
-export type TabType = 'session' | 'settings' | 'scheduled' | 'terminal'
+export type TabType = 'session' | 'settings' | 'scheduled' | 'terminal' | 'companion'
 
 export type Tab = {
   sessionId: string
@@ -152,7 +153,7 @@ export const useTabStore = create<TabStore>((set, get) => ({
 
   saveTabs: () => {
     const { tabs, activeTabId } = get()
-    const persistableTabs = tabs.filter((tab) => tab.type !== 'terminal')
+    const persistableTabs = tabs.filter((tab) => tab.type !== 'terminal' && tab.type !== 'companion')
     const data: TabPersistence = {
       openTabs: persistableTabs.map((t) => ({ sessionId: t.sessionId, title: t.title, type: t.type })),
       activeTabId: activeTabId && persistableTabs.some((tab) => tab.sessionId === activeTabId)
@@ -182,13 +183,13 @@ export const useTabStore = create<TabStore>((set, get) => ({
       const validTabs: Tab[] = data.openTabs
         .filter((t) => {
           // Special tabs are always valid
-          if (t.type === 'settings' || t.type === 'scheduled') return true
+          if (t.type === 'settings' || t.type === 'scheduled' || t.type === 'companion') return true
           if (t.type === 'terminal') return false
           // Session tabs must exist on server
           return existingIds.has(t.sessionId)
         })
         .map((t) => {
-          if (t.type === 'settings' || t.type === 'scheduled') {
+          if (t.type === 'settings' || t.type === 'scheduled' || t.type === 'companion') {
             return { sessionId: t.sessionId, title: t.title, type: t.type, status: 'idle' as const }
           }
           return {

desktop/src/types/companion.ts

@@ -0,0 +1,20 @@
+export type CompanionStatus = 'disconnected' | 'connecting' | 'connected' | 'error'
+
+export type CompanionConfig = {
+  serverUrl: string
+  voiceName: string
+}
+
+// Server -> Client (text frame)
+export type CompanionServerMessage =
+  | { type: 'vad'; speaking: boolean }
+  | { type: 'generating' }
+  | { type: 'text'; content: string }
+  | { type: 'done'; interrupted: boolean }
+
+// Client -> Server (text frame)
+export type CompanionClientMessage =
+  | { type: 'frame'; data: string }
+  | { type: 'stop' }
+  | { type: 'end' }
+  | { type: 'context'; voice?: string }