Clui CC — Claude Code 的命令行用户界面

一款轻量级、透明的桌面叠加层，适用于 macOS 上的 Claude Code。Clui CC 将 Claude Code CLI 包装在一个浮动药丸式界面中，支持多标签会话、权限审批 UI、语音输入以及技能市场。

演示

▶ 在 YouTube 上观看完整演示

功能

• 浮动叠加层 — 透明、可穿透的窗口，始终位于最上层。可通过 ⌥ + Space 切换（备用快捷键：Cmd+Shift+K）。
• 多标签会话 — 每个标签页都会启动一个独立的 claude -p 进程，拥有独立的会话状态。
• 权限审批 UI — 通过 PreToolUse HTTP 钩子拦截工具调用，以便您可以在界面上审查并批准或拒绝。
• 对话历史 — 浏览并恢复过去的 Claude Code 会话。
• 技能市场 — 无需离开 Clui CC 即可从 Anthropic 的 GitHub 仓库安装插件。
• 语音输入 — 使用 Whisper 进行本地语音转文本（必需，会自动安装）。
• 文件与截图附件 — 直接粘贴图片或附加文件。
• 双主题模式 — 暗色/亮色模式，并支持跟随系统设置。

为什么选择 Clui CC

• Claude Code，但更直观 — 保留 CLI 的强大功能，同时获得用于审批、历史记录和多任务处理的快速桌面用户体验。
• 人机协作安全性 — 工具调用会在执行前于应用内进行审查和批准。
• 会话原生工作流 — 每个标签页运行一个独立的 Claude 会话，您可以稍后继续使用。
• 本地优先 — 所有操作都通过您本地的 Claude CLI 运行。无遥测数据，无云端依赖。

工作原理

UI 提示 → 主进程启动 claude -p → NDJSON 流 → 实时渲染
                                         → 是否调用工具？ → 权限 UI → 批准/拒绝

完整的深入解析请参阅 docs/ARCHITECTURE.md。

安装应用（推荐）

以常规 Mac 应用程序形式运行 Clui CC 的最快方式。此方法会安装依赖项、语音支持（Whisper）、构建应用程序、将其复制到 /Applications 并启动它。

1) 克隆仓库

git clone https://github.com/lcoutodemos/clui-cc.git

2) 双击 install-app.command

在 Finder 中打开 clui-cc 文件夹，然后双击 install-app.command。

首次启动： macOS 可能会阻止该应用，因为它未签名。请前往 系统设置 → 隐私与安全性 → 仍要打开。您只需执行此操作一次。 清理文件夹： 安装程序会在成功安装后删除临时的 dist/ 和 release/ 文件夹，以保持仓库整洁。

首次安装完成后，只需从“应用程序”文件夹或 Spotlight 中打开 Clui CC 即可。

git clone https://github.com/lcoutodemos/clui-cc.git

cd clui-cc

./commands/setup.command

./commands/start.command

./commands/stop.command

npm install

npm run dev

xcode-select --install

brew install node

node --version

python3 -m pip install --upgrade pip setuptools

npm install -g @anthropic-ai/claude-code

claude

# Apple Silicon（M1/M2/M3/M4）— 推荐：
brew install whisperkit-cli
# Apple Silicon 备用方案，或 Intel Mac：
brew install whisper-cpp

src/
├── main/                   # Electron 主进程
│   ├── claude/             # 控制平面、运行管理器、事件归一化器
│   ├── hooks/              # 权限服务器（PreToolUse HTTP 钩子）
│   ├── marketplace/        # 插件目录获取 + 安装
│   ├── skills/             # 技能自动安装程序
│   └── index.ts            # 窗口创建、IPC 处理程序、系统托盘
├── renderer/               # React 前端
│   ├── components/         # 标签栏、对话视图、输入栏等
│   ├── stores/             # Zustand 会话存储
│   ├── hooks/              # 事件监听器、健康状态同步
│   └── theme.ts            # 双色板 + CSS 自定义属性
├── preload/                # 安全 IPC 桥（window.clui API）
└── shared/                 # 统一类型、IPC 通道定义

故障排除

有关设置问题和恢复命令，请参阅 docs/TROUBLESHOOTING.md。

快速自检命令：

npm run doctor

测试环境

已知限制

• 仅支持 macOS — 透明叠加层、系统托盘图标和 node-pty 均为 macOS 特有功能。目前尚未实现 Windows 和 Linux 支持。
• 需要 Claude Code CLI — Clui CC 是一个 UI 层，而非独立的 AI 客户端。您需要一个已认证的 claude CLI。
• 权限模式 — 使用 --permission-mode default。PTY 交互式传输属于遗留功能，默认已禁用。

许可证

MIT

Clui CC 快速上手指南

Clui CC 是一款专为 macOS 设计的轻量级桌面悬浮工具，为 Claude Code CLI 提供可视化交互界面。它支持多标签会话、权限审批、语音输入及技能市场，让你在保留命令行强大能力的同时，享受便捷的图形化操作体验。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS 13.0 (Ventura) 或更高版本（推荐 macOS 15 Sequoia）。
• Node.js：版本 18+（推荐 LTS 版本 20 或 22）。
• Python：版本 3.12+（需安装 setuptools）。
• Claude Code CLI：已安装并登录的 Anthropic Claude Code 命令行工具。
• Xcode 命令行工具：用于编译原生模块。

前置依赖安装

请按顺序在终端执行以下命令完成环境配置：

1. 安装 Xcode 命令行工具

   xcode-select --install
   

2. 安装 Node.js 推荐使用 Homebrew 安装：

   brew install node
   

   验证安装：

   node --version
   

3. 配置 Python 环境 Python 3.12+ 默认缺少 setuptools，需手动安装：

   python3 -m pip install --upgrade pip setuptools
   

4. 安装 Claude Code CLI 并登录

   npm install -g @anthropic-ai/claude-code
   claude
   

   执行 claude 后按提示完成身份验证（需 Pro/Team/Enterprise 订阅）。

5. 安装语音输入支持 (Whisper) 根据你的芯片架构选择其一：

   • Apple Silicon (M1/M2/M3/M4) - 推荐：

     brew install whisperkit-cli
     

   • Intel Mac 或备用方案：

     brew install whisper-cpp
     

注意：本项目无需配置 API Key 或 .env 文件，直接复用本地 Claude CLI 的认证状态。

安装步骤

你可以通过图形化脚本一键安装，或通过终端命令进行开发者模式安装。

方式一：图形化安装（推荐）

适合大多数用户，会自动构建应用并复制到 /Applications 目录。

1. 克隆仓库

   git clone https://github.com/lcoutodemos/clui-cc.git
   

2. 运行安装脚本 在 Finder 中打开 clui-cc 文件夹，双击运行 install-app.command。

3. 首次启动授权 如果 macOS 提示“无法打开，因为来自身份不明的开发者”：

   • 前往 系统设置 → 隐私与安全性。
   • 点击 仍要打开 (Open Anyway)。

安装完成后，即可在“应用程序”文件夹或通过 Spotlight 搜索 "Clui CC" 启动。

方式二：终端命令安装（开发者模式）

如果你希望从源码运行或进行开发调试：

git clone https://github.com/lcoutodemos/clui-cc.git
cd clui-cc
./commands/setup.command
./commands/start.command

停止运行：

./commands/stop.command

基本使用

安装完成后，按照以下步骤开始使用：

1. 启动/隐藏界面

   • 默认快捷键：Option (⌥) + Space
   • 备用快捷键（若冲突）：Cmd + Shift + K
   • 界面将以透明悬浮胶囊形式出现在屏幕顶层，支持穿透点击。

2. 创建会话

   • 点击界面上的 + 号新建标签页。
   • 每个标签页都会独立启动一个 claude -p 进程，拥有独立的会话状态。

3. 交互与审批

   • 输入：直接在输入框打字，或使用语音输入（自动调用本地 Whisper）。
   • 附件：支持直接粘贴截图或拖拽文件到输入框。
   • 权限审批：当 Claude 尝试执行工具调用（如写文件、运行命令）时，界面会弹出审批窗口，你需要手动点击 Approve (允许) 或 Deny (拒绝) 才能继续执行，确保操作安全。

4. 管理历史

   • 通过界面浏览过往会话记录，可随时恢复之前的对话上下文。
   • 可在内置的 "Skills Marketplace" 中安装官方插件扩展功能。

5. 切换主题

   • 支持深色/浅色模式，并可跟随 macOS 系统设置自动切换。