Clui Cc Claude Overlay

1---2name: clui-cc-claude-overlay3description: Command Line User Interface for Claude Code — a floating macOS desktop overlay with multi-tab sessions, permission approval UI, voice input, and skills marketplace.4triggers:5  - set up clui cc6  - add floating overlay for claude code7  - install clui cc on mac8  - how to use clui cc9  - configure claude code desktop ui10  - add permission approval ui for claude code11  - clui cc multi-tab sessions12  - voice input for claude code13---14 15# Clui CC — Claude Code Desktop Overlay16 17> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.18 19Clui CC wraps the Claude Code CLI in a transparent, floating macOS overlay with multi-tab sessions, a permission approval UI (PreToolUse HTTP hooks), voice input via Whisper, conversation history, and a skills marketplace. It requires an authenticated `claude` CLI and runs entirely local — no telemetry or cloud dependency.20 21---22 23## Prerequisites24 25| Requirement | Minimum | Notes |26|---|---|---|27| macOS | 13+ | Overlay is macOS-only |28| Node.js | 18+ | LTS 20 or 22 recommended |29| Python | 3.10+ | Needs `setuptools` on 3.12+ |30| Claude Code CLI | any | Must be authenticated |31| Whisper CLI | any | For voice input |32 33```bash34# 1. Xcode CLI tools (native module compilation)35xcode-select --install36 37# 2. Node.js via Homebrew38brew install node39node --version   # confirm ≥1840 41# 3. Python setuptools (required on Python 3.12+)42python3 -m pip install --upgrade pip setuptools43 44# 4. Claude Code CLI45npm install -g @anthropic-ai/claude-code46 47# 5. Authenticate Claude Code48claude49 50# 6. Whisper for voice input51brew install whisper-cli52```53 54---55 56## Installation57 58### Recommended: App installer (non-developer)59 60```bash61git clone https://github.com/lcoutodemos/clui-cc.git62# Then open the clui-cc folder in Finder and double-click install-app.command63```64 65On first launch macOS may block the unsigned app — go to **System Settings → Privacy & Security → Open Anyway**.66 67### Developer workflow68 69```bash70git clone https://github.com/lcoutodemos/clui-cc.git71cd clui-cc72npm install73npm run dev       # Hot-reloads renderer; restart for main-process changes74```75 76### Command scripts77 78```bash79./commands/setup.command    # Environment check + install deps80./commands/start.command    # Build and launch from source81./commands/stop.command     # Stop all Clui CC processes82 83npm run build               # Production build (no packaging)84npm run dist                # Package as macOS .app → release/85npm run doctor              # Environment diagnostic86```87 88---89 90## Key Shortcuts91 92| Shortcut | Action |93|---|---|94| `⌥ + Space` | Show / hide the overlay |95| `Cmd + Shift + K` | Fallback toggle (if ⌥+Space is claimed) |96 97---98 99## Architecture100 101```102UI prompt → Main process spawns claude -p → NDJSON stream → live render103                                         → tool call? → permission UI → approve/deny104```105 106### Process flow107 1081. Each tab spawns `claude -p --output-format stream-json` as a subprocess.1092. `RunManager` parses NDJSON; `EventNormalizer` normalizes events.1103. `ControlPlane` manages tab lifecycle: `connecting → idle → running → completed/failed/dead`.1114. Tool permission requests arrive via HTTP hooks to `PermissionServer` (localhost only).1125. Renderer polls backend health every 1.5 s and reconciles tab state.1136. Sessions resume with `--resume <session-id>`.114 115### Project structure116 117```118src/119├── main/120│   ├── claude/       # ControlPlane, RunManager, EventNormalizer121│   ├── hooks/        # PermissionServer (PreToolUse HTTP hooks)122│   ├── marketplace/  # Plugin catalog fetch + install123│   ├── skills/       # Skill auto-installer124│   └── index.ts      # Window creation, IPC handlers, tray125├── renderer/126│   ├── components/   # TabStrip, ConversationView, InputBar, …127│   ├── stores/       # Zustand session store128│   ├── hooks/        # Event listeners, health reconciliation129│   └── theme.ts      # Dual palette + CSS custom properties130├── preload/          # Secure IPC bridge (window.clui API)131└── shared/           # Canonical types, IPC channel definitions132```133 134---135 136## IPC API (`window.clui`)137 138The preload bridge exposes `window.clui` in the renderer. Key methods:139 140```typescript141// Send a prompt to the active tab's claude process142window.clui.sendPrompt(tabId: string, text: string): Promise<void>143 144// Approve or deny a pending tool-use permission145window.clui.resolvePermission(requestId: string, approved: boolean): Promise<void>146 147// Create a new tab (spawns a new claude -p process)148window.clui.createTab(): Promise<{ tabId: string }>149 150// Resume a past session by id151window.clui.resumeSession(tabId: string, sessionId: string): Promise<void>152 153// Subscribe to normalized events from a tab154window.clui.onTabEvent(tabId: string, callback: (event: NormalizedEvent) => void): () => void155 156// Get conversation history list157window.clui.getHistory(): Promise<SessionMeta[]>158```159 160---161 162## Working with Tabs and Sessions163 164### Creating a tab and sending a prompt (renderer)165 166```typescript167import { useEffect, useState } from 'react'168 169export function useClaudeTab() {170  const [tabId, setTabId] = useState<string | null>(null)171  const [messages, setMessages] = useState<NormalizedEvent[]>([])172 173  useEffect(() => {174    window.clui.createTab().then(({ tabId }) => {175      setTabId(tabId)176 177      const unsubscribe = window.clui.onTabEvent(tabId, (event) => {178        setMessages((prev) => [...prev, event])179      })180 181      return unsubscribe182    })183  }, [])184 185  const send = (text: string) => {186    if (!tabId) return187    window.clui.sendPrompt(tabId, text)188  }189 190  return { messages, send }191}192```193 194### Resuming a past session195 196```typescript197async function resumeLastSession() {198  const history = await window.clui.getHistory()199  if (history.length === 0) return200 201  const { tabId } = await window.clui.createTab()202  const lastSession = history[0] // most recent first203  await window.clui.resumeSession(tabId, lastSession.sessionId)204}205```206 207---208 209## Permission Approval UI210 211Tool calls are intercepted by `PermissionServer` via PreToolUse HTTP hooks before execution. The renderer receives a `permission_request` event and must resolve it.212 213```typescript214// Renderer: listen for permission requests215window.clui.onTabEvent(tabId, async (event) => {216  if (event.type !== 'permission_request') return217 218  const { requestId, toolName, toolInput } = event219 220  // Show your approval UI, then:221  const approved = await showApprovalDialog({ toolName, toolInput })222  await window.clui.resolvePermission(requestId, approved)223})224```225 226```typescript227// Main process: PermissionServer registers a hook with claude -p228// The hook endpoint receives POST requests from Claude Code like:229// { "tool": "bash", "input": { "command": "rm -rf dist/" }, "session_id": "..." }230// It holds the request until the renderer resolves it.231```232 233---234 235## Voice Input236 237Voice input uses Whisper locally. It is installed automatically by `install-app.command` or via `brew install whisper-cli`. No API key is needed — transcription runs entirely on-device.238 239```typescript240// Triggered from InputBar component via IPC241window.clui.startVoiceInput(): Promise<void>242window.clui.stopVoiceInput(): Promise<{ transcript: string }>243```244 245---246 247## Skills Marketplace248 249Install skills (plugins) from Anthropic's GitHub repos without leaving the UI.250 251```typescript252// Fetch available skills (cached 5 min, fetched from raw.githubusercontent.com)253const skills = await window.clui.marketplace.list()254// [{ id, name, description, repoUrl, version }, ...]255 256// Install a skill (downloads tarball from api.github.com)257await window.clui.marketplace.install(skillId: string)258 259// List installed skills260const installed = await window.clui.marketplace.listInstalled()261```262 263Network calls made by the marketplace:264 265| Endpoint | Purpose | Required |266|---|---|---|267| `raw.githubusercontent.com/anthropics/*` | Skill catalog (5 min cache) | No — graceful fallback |268| `api.github.com/repos/anthropics/*/tarball/*` | Skill tarball download | No — skipped on failure |269 270---271 272## Theme Configuration273 274```typescript275// src/renderer/theme.ts — dual palette with CSS custom properties276// Toggle via the UI or programmatically:277window.clui.setTheme('dark' | 'light' | 'system')278```279 280Custom CSS properties are applied to `:root` and can be overridden in renderer stylesheets:281 282```css283:root {284  --clui-bg: rgba(20, 20, 20, 0.85);285  --clui-text: #f0f0f0;286  --clui-accent: #7c5cfc;287  --clui-pill-radius: 24px;288}289```290 291---292 293## Adding a Custom Skill294 295Skills are auto-loaded from `~/.clui/skills/`. A skill is a directory with a `skill.js` entry:296 297```typescript298// ~/.clui/skills/my-skill/skill.js299module.exports = {300  name: 'my-skill',301  version: '1.0.0',302  description: 'Does something useful',303 304  // Called when the skill is activated by a matching prompt305  async onPrompt(context) {306    const { prompt, tabId, clui } = context307    if (!prompt.includes('my trigger')) return false   // pass through308 309    await clui.sendMessage(tabId, `Handled by my-skill: ${prompt}`)310    return true  // consumed — don't forward to claude311  },312}313```314 315---316 317## Troubleshooting318 319### Self-check320 321```bash322npm run doctor323```324 325### Common issues326 327**App blocked on first launch**328→ System Settings → Privacy & Security → Open Anyway329 330**`node-pty` fails to compile**331```bash332xcode-select --install333python3 -m pip install --upgrade pip setuptools334npm install335```336 337**`claude` not found**338```bash339npm install -g @anthropic-ai/claude-code340claude   # authenticate341which claude   # confirm it's on PATH342```343 344**Whisper not found**345```bash346brew install whisper-cli347which whisper-cli348```349 350**Port conflict on PermissionServer**351The HTTP hook server runs on localhost only. If another process occupies its port, restart with:352```bash353./commands/stop.command354./commands/start.command355```356 357**`setuptools` missing (Python 3.12+)**358```bash359python3 -m pip install --upgrade pip setuptools360```361 362**Overlay not showing**363- Try the fallback shortcut: `Cmd + Shift + K`364- Check that Clui CC has Accessibility permission: System Settings → Privacy & Security → Accessibility365 366---367 368## Tested Versions369 370| Component | Version |371|---|---|372| macOS | 15.x Sequoia |373| Node.js | 20.x LTS, 22.x |374| Python | 3.12 (+ setuptools) |375| Electron | 33.x |376| Claude Code CLI | 2.1.71 |377 378---379 380## References381 382- [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code)383- [Architecture deep-dive](docs/ARCHITECTURE.md)384- [Troubleshooting guide](docs/TROUBLESHOOTING.md)385- [MIT License](LICENSE)