Clui CC — Claude Code 桌面覆盖层

技能来自 ara.so — Daily 2026 Skills 系列。

Clui CC 将 Claude Code CLI 包装在一个透明的、浮动式的 macOS 覆盖层中，提供多标签会话、权限审批界面（PreToolUse HTTP 钩子）、通过 Whisper 实现的语音输入、对话历史记录以及技能市场。它需要已认证的 claude CLI，并且完全在本地运行——无遥测或云依赖。

先决条件

# 1. Xcode 命令行工具 (原生模块编译)
xcode-select --install

# 2. 通过 Homebrew 安装 Node.js
brew install node
node --version   # 确认 ≥18

# 3. Python setuptools (Python 3.12+ 必需)
python3 -m pip install --upgrade pip setuptools

# 4. Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 5. 认证 Claude Code
claude

# 6. 用于语音输入的 Whisper
brew install whisper-cli

安装

推荐：应用安装程序（非开发者）

git clone https://github.com/lcoutodemos/clui-cc.git
# 然后在访达中打开 clui-cc 文件夹，双击 install-app.command

首次启动时，macOS 可能会阻止未签名的应用 — 前往 系统设置 → 隐私与安全性 → 仍要打开。

开发者工作流

git clone https://github.com/lcoutodemos/clui-cc.git
cd clui-cc
npm install
npm run dev       # 热重载渲染进程；主进程更改需重启

命令脚本

./commands/setup.command    # 环境检查 + 安装依赖
./commands/start.command    # 从源码构建并启动
./commands/stop.command     # 停止所有 Clui CC 进程

npm run build               # 生产构建（不打包）
npm run dist                # 打包为 macOS .app → release/
npm run doctor              # 环境诊断

主要快捷键

架构

UI 提示 → 主进程派生 claude -p → NDJSON 流 → 实时渲染
                                         → 工具调用？→ 权限界面 → 批准/拒绝

流程

1. 每个标签页派生一个 claude -p --output-format stream-json 子进程。
2. RunManager 解析 NDJSON；EventNormalizer 规范化事件。
3. ControlPlane 管理标签页生命周期：connecting → idle → running → completed/failed/dead。
4. 工具权限请求通过 HTTP 钩子到达 PermissionServer（仅限 localhost）。
5. 渲染进程每 1.5 秒轮询后端健康状态，并协调标签页状态。
6. 使用 --resume <session-id> 恢复会话。

项目结构

src/
├── main/
│   ├── claude/       # ControlPlane, RunManager, EventNormalizer
│   ├── hooks/        # PermissionServer (PreToolUse HTTP 钩子)
│   ├── marketplace/  # 插件目录获取 + 安装
│   ├── skills/       # 技能自动安装器
│   └── index.ts      # 窗口创建、IPC 处理程序、托盘
├── renderer/
│   ├── components/   # TabStrip, ConversationView, InputBar, …
│   ├── stores/       # Zustand 会话存储
│   ├── hooks/        # 事件监听器、健康状态协调
│   └── theme.ts      # 双调色板 + CSS 自定义属性
├── preload/          # 安全 IPC 桥接 (window.clui API)
└── shared/           # 规范类型、IPC 通道定义

IPC API (window.clui)

预加载桥接在渲染进程中暴露了 window.clui。主要方法：

// 向活动标签页的 claude 进程发送提示
window.clui.sendPrompt(tabId: string, text: string): Promise<void>

// 批准或拒绝待处理的工具使用权限
window.clui.resolvePermission(requestId: string, approved: boolean): Promise<void>

// 创建新标签页（派生新的 claude -p 进程）
window.clui.createTab(): Promise<{ tabId: string }>

// 通过 id 恢复过去的会话
window.clui.resumeSession(tabId: string, sessionId: string): Promise<void>

// 订阅来自标签页的规范化事件
window.clui.onTabEvent(tabId: string, callback: (event: NormalizedEvent) => void): () => void

// 获取对话历史列表
window.clui.getHistory(): Promise<SessionMeta[]>

使用标签页和会话

创建标签页并发送提示（渲染进程）

import { useEffect, useState } from 'react'

export function useClaudeTab() {
  const [tabId, setTabId] = useState<string | null>(null)
  const [messages, setMessages] = useState<NormalizedEvent[]>([])

  useEffect(() => {
    window.clui.createTab().then(({ tabId }) => {
      setTabId(tabId)

      const unsubscribe = window.clui.onTabEvent(tabId, (event) => {
        setMessages((prev) => [...prev, event])
      })

      return unsubscribe
    })
  }, [])

  const send = (text: string) => {
    if (!tabId) return
    window.clui.sendPrompt(tabId, text)
  }

  return { messages, send }
}

恢复过去的会话

async function resumeLastSession() {
  const history = await window.clui.getHistory()
  if (history.length === 0) return

  const { tabId } = await window.clui.createTab()
  const lastSession = history[0] // 最新的在前
  await window.clui.resumeSession(tabId, lastSession.sessionId)
}

权限审批界面

工具调用在通过 PreToolUse HTTP 钩子执行前被 PermissionServer 拦截。渲染进程收到一个 permission_request 事件，必须对其进行处理。

// 渲染进程：监听权限请求
window.clui.onTabEvent(tabId, async (event) => {
  if (event.type !== 'permission_request') return

  const { requestId, toolName, toolInput } = event

  // 显示你的审批界面，然后：
  const approved = await showApprovalDialog({ toolName, toolInput })
  await window.clui.resolvePermission(requestId, approved)
})

// 主进程：PermissionServer 向 claude -p 注册一个钩子
// 钩子端点接收来自 Claude Code 的 POST 请求，例如：
// { "tool": "bash", "input": { "command": "rm -rf dist/" }, "session_id": "..." }
// 它会保留该请求，直到渲染进程处理完毕。

语音输入

语音输入使用本地的 Whisper。它由 install-app.command 自动安装，或通过 brew install whisper-cli 安装。无需 API 密钥 — 转录完全在设备上进行。

// 通过 IPC 从 InputBar 组件触发
window.clui.startVoiceInput(): Promise<void>
window.clui.stopVoiceInput(): Promise<{ transcript: string }>

技能市场

无需离开界面即可从 Anthropic 的 GitHub 仓库安装技能（插件）。

// 获取可用技能（缓存 5 分钟，从 raw.githubusercontent.com 获取）
const skills = await window.clui.marketplace.list()
// [{ id, name, description, repoUrl, version }, ...]

// 安装一个技能（从 api.github.com 下载 tarball）
await window.clui.marketplace.install(skillId: string)

// 列出已安装的技能
const installed = await window.clui.marketplace.listInstalled()

市场进行的网络调用：

主题配置

// src/renderer/theme.ts — 带有 CSS 自定义属性的双调色板
// 通过界面或编程方式切换：
window.clui.setTheme('dark' | 'light' | 'system')

自定义 CSS 属性被应用到 :root，并可以在渲染进程样式表中覆盖：

:root {
  --clui-bg: rgba(20, 20, 20, 0.85);
  --clui-text: #f0f0f0;
  --clui-accent: #7c5cfc;
  --clui-pill-radius: 24px;
}

添加自定义技能

技能从 ~/.clui/skills/ 自动加载。一个技能是一个包含 skill.js 入口的目录：

// ~/.clui/skills/my-skill/skill.js
module.exports = {
  name: 'my-skill',
  version: '1.0.0',
  description: 'Does something useful',

  // 当技能被匹配的提示触发时调用
  async onPrompt(context) {
    const { prompt, tabId, clui } = context
    if (!prompt.includes('my trigger')) return false   // 传递

    await clui.sendMessage(tabId, `由 my-skill 处理: ${prompt}`)
    return true  // 已消费 — 不转发给 claude
  },
}

故障排除

自检

npm run doctor

常见问题

首次启动应用被阻止
→ 系统设置 → 隐私与安全性 → 仍要打开

node-pty 编译失败

xcode-select --install
python3 -m pip install --upgrade pip setuptools
npm install

找不到 claude

npm install -g @anthropic-ai/claude-code
claude   # 认证
which claude   # 确认在 PATH 中

找不到 Whisper

brew install whisper-cli
which whisper-cli

PermissionServer 端口冲突
HTTP 钩子服务器仅在 localhost 上运行。如果其他进程占用了它的端口，请重启：

./commands/stop.command
./commands/start.command

缺少 setuptools（Python 3.12+）

python3 -m pip install --upgrade pip setuptools

覆盖层未显示

• 尝试备用快捷键：Cmd + Shift + K
• 检查 Clui CC 是否有辅助功能权限：系统设置 → 隐私与安全性 → 辅助功能

测试版本

参考资料

• Claude Code 文档
• 架构深入分析
• 故障排除指南
• MIT 许可证