Hooks

Hooks 模块是 Claude Code 的 React Hooks 生态系统，包含 80+ 个自定义 Hook 和 2 个子目录（notifs/、toolPermission/）。Hooks 覆盖六大领域：AI 交互（useAssistantHistory、useCancelRequest、useMainLoopModel）、IDE 集成（useIDEIntegration、useIdeConnectionStatus、useDiffInIDE）、输入处理（useTextInput、useVimInput、usePasteHandler、useInputBuffer）、语音交互（useVoice、useVoiceEnabled、useVoiceIntegration）、任务管理（useTasksV2、useTaskListWatcher、useScheduledTasks）、以及 UI 状态（useVirtualScroll、useTerminalSize、useBlink、useElapsedTime）。每个 Hook 封装一个独立的副作用域。

职责与设计理念

职责说明

80+ 个 React Hooks 库，覆盖 AI 交互、IDE 集成、语音、任务等全场景

设计理念

Hook 即副作用边界——每个 Hook 封装一个独立的副作用域（网络请求、事件监听、定时器），组件通过组合 Hooks 而非继承来获得能力。80+ Hooks 不是碎片化，而是关注点分离的极致体现。

架构决策

为什么 80+ Hooks 不合并为更少的"超级 Hook"？

每个 Hook 封装一个独立的副作用域

合并 Hook 会导致不需要语音功能的组件也加载语音相关的副作用。独立 Hook 让组件按需组合，未使用的 Hook 不会产生任何运行时开销。这是 React Hooks 设计哲学的忠实实践。

文件清单

文件名	用途
useTextInput.ts	文本输入 Hook，管理多行编辑、光标位置和输入缓冲
useVirtualScroll.ts	虚拟滚动 Hook，实现大列表的高性能渲染
useIDEIntegration.tsx	IDE 集成 Hook，管理与 VS Code 等编辑器的双向通信
useVoiceIntegration.tsx	语音集成 Hook，管理语音输入的录音、转写和提交
useCommandKeybindings.tsx	命令快捷键 Hook，将快捷键事件路由到命令处理器
useGlobalKeybindings.tsx	全局快捷键 Hook，处理应用级快捷键（ctrl+c/d/l 等）
useSwarmInitialization.ts	Swarm 初始化 Hook，管理多 Agent 集群的启动
toolPermission/	工具权限 Hooks 目录，管理工具执行的授权状态

使用场景

VS Code 中选中代码后在 Claude Code 中提问

useIDEIntegration 监听 IDE 选区变化，自动将选中代码作为上下文

语音输入 "fix this bug"

useVoiceIntegration 管理录音 → 转写 → 提交的完整流程

麦克风 → useVoice 录音 → 转写 API → useTextInput 填充 → 提交

依赖关系

Context — 9 个 React Context Provider，管理 UI 层的全局状态分发
Ink — 深度定制的终端渲染引擎，基于 Yoga 布局 + React Reconciler 实现终端 UI
Keybindings — 可定制快捷键系统，支持多上下文、和弦组合与平台适配

关键代码片段

IDE 集成 Hook

function useIDEIntegration() {
  const [connectionStatus] = useIdeConnectionStatus()
  const [selection] = useIdeSelection()

  useEffect(() => {
    const unsub = onIdeFileChange((file) => {
      // 同步文件状态到 Claude Code
    })
    return unsub
  }, [])

  return {
    isConnected: connectionStatus === 'connected',
    selectedText: selection?.text,
    openFile: (path) => sendToIde('openFile', { path }),
    showDiff: (diff) => sendToIde('showDiff', { diff }),
  }
}

双向通信：监听 IDE 事件 + 向 IDE 发送命令，实现编辑器深度集成

虚拟滚动 Hook

function useVirtualScroll(items: unknown[], itemHeight: number) {
  const [scrollTop, setScrollTop] = useState(0)
  const terminalHeight = useTerminalSize().rows

  const visibleRange = useMemo(() => {
    const start = Math.floor(scrollTop / itemHeight)
    const end = Math.min(
      start + Math.ceil(terminalHeight / itemHeight) + 1,
      items.length
    )
    return { start, end }
  }, [scrollTop, terminalHeight, items.length])

  // 只渲染可视区域内的项目
  return { visibleItems: items.slice(visibleRange.start, visibleRange.end) }
}

只渲染可视区域内的项目，支持数千条消息的流畅滚动

技术笔记

performance

虚拟滚动优化

useVirtualScroll 只渲染可视区域 ± 1 行的缓冲区，滚动时通过 translateY 偏移模拟完整列表，避免渲染数千个 DOM 节点。