Clui CC — Claude Code Desktop Overlay

Skill by ara.so — Daily 2026 Skills collection.

Clui 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.

---

Prerequisites

Requirement	Minimum	Notes
macOS	13+	Overlay is macOS-only
Node.js	18+	LTS 20 or 22 recommended
Python	3.10+	Needs setuptools on 3.12+
Claude Code CLI	any	Must be authenticated
Whisper CLI	any	For voice input

# 1. Xcode CLI tools (native module compilation)
xcode-select --install

# 2. Node.js via Homebrew
brew install node
node --version   # confirm ≥18

# 3. Python setuptools (required on Python 3.12+)
python3 -m pip install --upgrade pip setuptools

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

# 5. Authenticate Claude Code
claude

# 6. Whisper for voice input
brew install whisper-cli

---

Installation

Recommended: App installer (non-developer)

git clone https://github.com/lcoutodemos/clui-cc.git
# Then open the clui-cc folder in Finder and double-click install-app.command

On first launch macOS may block the unsigned app — go to System Settings → Privacy & Security → Open Anyway.

Developer workflow

git clone https://github.com/lcoutodemos/clui-cc.git
cd clui-cc
npm install
npm run dev       # Hot-reloads renderer; restart for main-process changes

Command scripts

./commands/setup.command    # Environment check + install deps
./commands/start.command    # Build and launch from source
./commands/stop.command     # Stop all Clui CC processes

npm run build               # Production build (no packaging)
npm run dist                # Package as macOS .app → release/
npm run doctor              # Environment diagnostic

---

Key Shortcuts

Shortcut	Action
⌥ + Space	Show / hide the overlay
Cmd + Shift + K	Fallback toggle (if ⌥+Space is claimed)

---

Architecture

UI prompt → Main process spawns claude -p → NDJSON stream → live render
                                         → tool call? → permission UI → approve/deny

Process flow

1. Each tab spawns claude -p --output-format stream-json as a subprocess.
2. RunManager parses NDJSON; EventNormalizer normalizes events.
3. ControlPlane manages tab lifecycle: connecting → idle → running → completed/failed/dead.
4. Tool permission requests arrive via HTTP hooks to PermissionServer (localhost only).
5. Renderer polls backend health every 1.5 s and reconciles tab state.
6. Sessions resume with --resume <session-id>.

Project structure

src/
├── main/
│   ├── claude/       # ControlPlane, RunManager, EventNormalizer
│   ├── hooks/        # PermissionServer (PreToolUse HTTP hooks)
│   ├── marketplace/  # Plugin catalog fetch + install
│   ├── skills/       # Skill auto-installer
│   └── index.ts      # Window creation, IPC handlers, tray
├── renderer/
│   ├── components/   # TabStrip, ConversationView, InputBar, …
│   ├── stores/       # Zustand session store
│   ├── hooks/        # Event listeners, health reconciliation
│   └── theme.ts      # Dual palette + CSS custom properties
├── preload/          # Secure IPC bridge (window.clui API)
└── shared/           # Canonical types, IPC channel definitions

---

IPC API (window.clui)

The preload bridge exposes window.clui in the renderer. Key methods:

// Send a prompt to the active tab's claude process
window.clui.sendPrompt(tabId: string, text: string): Promise<void>

// Approve or deny a pending tool-use permission
window.clui.resolvePermission(requestId: string, approved: boolean): Promise<void>

// Create a new tab (spawns a new claude -p process)
window.clui.createTab(): Promise<{ tabId: string }>

// Resume a past session by id
window.clui.resumeSession(tabId: string, sessionId: string): Promise<void>

// Subscribe to normalized events from a tab
window.clui.onTabEvent(tabId: string, callback: (event: NormalizedEvent) => void): () => void

// Get conversation history list
window.clui.getHistory(): Promise<SessionMeta[]>

---

Working with Tabs and Sessions

Creating a tab and sending a prompt (renderer)

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 }
}

Resuming a past session

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

  const { tabId } = await window.clui.createTab()
  const lastSession = history[0] // most recent first
  await window.clui.resumeSession(tabId, lastSession.sessionId)
}

---

Permission Approval UI

Tool calls are intercepted by PermissionServer via PreToolUse HTTP hooks before execution. The renderer receives a permission_request event and must resolve it.

// Renderer: listen for permission requests
window.clui.onTabEvent(tabId, async (event) => {
  if (event.type !== 'permission_request') return

  const { requestId, toolName, toolInput } = event

  // Show your approval UI, then:
  const approved = await showApprovalDialog({ toolName, toolInput })
  await window.clui.resolvePermission(requestId, approved)
})

// Main process: PermissionServer registers a hook with claude -p