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
Installation
Recommended: App installer (non-developer)
On first launch macOS may block the unsigned app — go to System Settings → Privacy & Security → Open Anyway.
Developer workflow
Command scripts
Key Shortcuts
Architecture
Process flow
- Each tab spawns
claude -p --output-format stream-jsonas a subprocess. RunManagerparses NDJSON;EventNormalizernormalizes events.ControlPlanemanages tab lifecycle:connecting → idle → running → completed/failed/dead.- Tool permission requests arrive via HTTP hooks to
PermissionServer(localhost only). - Renderer polls backend health every 1.5 s and reconciles tab state.
- Sessions resume with
--resume <session-id>.
Project structure
IPC API (window.clui)
The preload bridge exposes window.clui in the renderer. Key methods:
Working with Tabs and Sessions
Creating a tab and sending a prompt (renderer)
Resuming a past session
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.
Voice Input
Voice 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.
Skills Marketplace
Install skills (plugins) from Anthropic's GitHub repos without leaving the UI.
Network calls made by the marketplace:
Theme Configuration
Custom CSS properties are applied to :root and can be overridden in renderer stylesheets:
Adding a Custom Skill
Skills are auto-loaded from ~/.clui/skills/. A skill is a directory with a skill.js entry:
Troubleshooting
Self-check
Common issues
App blocked on first launch → System Settings → Privacy & Security → Open Anyway
node-pty fails to compile
claude not found
Whisper not found
Port conflict on PermissionServer The HTTP hook server runs on localhost only. If another process occupies its port, restart with:
setuptools missing (Python 3.12+)
Overlay not showing
- Try the fallback shortcut:
Cmd + Shift + K - Check that Clui CC has Accessibility permission: System Settings → Privacy & Security → Accessibility
Tested Versions
References
- Claude Code docs
- Architecture deep-dive [blocked]
- Troubleshooting guide [blocked]
- MIT License [blocked]


