BetterCC

A enhanced fork of Clui CC, originally created by Lucas Couto.
Transparent desktop overlay for the Claude Code CLI with multi-tab sessions, inline diffs, reasoning controls, permission approval, voice input, and a skills marketplace.

Original demo by Lucas Couto · Architecture · Troubleshooting · Report a Bug

---

About

BetterCC is a fork of Clui CC, the desktop overlay for Claude Code created by Lucas Couto. The original project wraps the Claude Code CLI in a floating Electron window with multi-tab sessions, permission approval, conversation history, voice input, and a skills marketplace.

This fork extends the original with significant new features, Windows platform support, bug fixes, and performance optimizations. All original features remain intact.

What This Fork Adds

Everything below was built on top of the original Clui CC by Gustavo Puhlmann:

Inline Diff Viewer

Every Edit and Write operation from Claude now displays a visual diff directly in the conversation. Uses an LCS algorithm to compute line-by-line changes: added lines in green, removed lines in red, with context for reference. Supports files up to 512KB and 2000 lines, with lazy expansion for large diffs.

Reasoning Effort Control

Four-level effort selector (Low / Medium / High / Max) available in settings and via /effort. Max effort is exclusive to Claude Opus 4.6 and unlocks full reasoning capacity. The active level is visible in the status bar with a gradient icon for Max.

Extended Thinking

Toggle Claude's internal reasoning via /thinking or settings. When enabled, thinking blocks appear as expandable sections in the conversation showing exactly how Claude arrived at its answer. Full support for thinking content blocks and delta events in the streaming pipeline.

Token Usage Tracking

Real-time per-session token accounting: input, output, cache read, and cache creation tokens. Displayed in the status bar with formatted counters. Use /cost after any task to see the full breakdown: USD cost, duration, turns, and token details.

Global Rules System

New "Rules" tab in settings with a system prompt textarea applied to all sessions across all directories. Persisted to localStorage. Useful for enforcing language preferences, coding standards, or behavioral instructions across every conversation.

MCP Server Management

Dedicated "MCP" tab in settings to view, add, and remove Model Context Protocol servers. Shows connection status (green/red/gray dots), supports stdio and HTTP server types, and allows configuration of commands, arguments, URLs, and environment variables.

Redesigned Settings Panel

Three-tab interface (Settings / Rules / MCP) replacing the original single-page popover. New controls for effort level, thinking mode, expanded UI, notification sounds, and theme. Spring-based animations and improved viewport positioning.

Windows Platform Support

Added npm run dist:win producing an x64 NSIS installer with configurable install directory. Core features (tabs, conversations, permissions, marketplace, diff viewer, settings) work on Windows. Platform-specific features like the transparent overlay and Option + Space shortcut remain macOS-only. Future Linux support is planned.

Warm Process Management

Completed Claude processes are kept alive for fast session resumption instead of being killed immediately. The ControlPlane now tracks warm handles per tab, enabling near-instant re-engagement with previous sessions.

Bug Fixes & Optimizations

• Fixed RAF/fallback race condition: buffered text chunks are now flushed before task_update and task_complete events
• Fixed missing assistant replies caused by dropped stream chunks during fast streaming
• Request staleness detection to suppress orphaned event streams from cancelled runs
• Better error diagnostics with stderr tail extraction for unknown errors
• Improved notification logic: notifications only fire when the window is hidden or the tab is not active
• Session settings (model, permission mode) now persist across restarts via localStorage
• Electron upgraded from 35.x to 37.x

Original Features (by Lucas Couto)

The following features come from the original Clui CC project:

• Floating overlay — transparent, click-through window on top of all workspaces, toggled with Option + Space
• Multi-tab sessions — each tab runs its own claude -p process with independent state, working directory, and model
• Permission approval — intercepts tool calls via HTTP hooks. Safe tools auto-approve; dangerous tools (Bash, Edit, Write) require explicit approval with sensitive fields masked
• Session history & resume — browse past sessions, search by message or directory, and resume any conversation with full context restored via --resume
• Voice input — local speech-to-text via Whisper with voice activity detection
• File & screenshot attachments — paste images, drag-and-drop files, capture screenshots
• Markdown rendering — GitHub-Flavored Markdown with syntax-highlighted code blocks, tables, and embedded images
• Skills marketplace — browse, search, and install plugins from Anthropic GitHub repos
• Slash commands — /model, /cost, /clear, /mcp, /skills, /help, and more
• Model selection — switch between Opus 4.6, Sonnet 4.6, and Haiku 4.5 per session
• Dual theme — dark and light mode with system-follow and glass-morphism aesthetic
• Working directory management — base directory picker plus additional directories via --add-dir
• Native notifications — task completion alerts when the overlay is hidden

Platform Support

Platform	Status	Details
macOS 13+	Full	Transparent overlay, system tray, global shortcuts, native notifications
Windows 10+	Partial	NSIS installer (x64). Tabs, conversations, permissions, marketplace, diffs, and settings work. Overlay transparency and tray are limited
Linux	Planned	Future support. Contributions welcome

Installation

One-Click (macOS)

git clone https://github.com/gustavohenrip/ClaudeCode-Better.git

Open the folder in Finder and double-click install-app.command. This handles dependencies, Whisper, build, and launch.

First launch: macOS blocks unsigned apps. Go to System Settings > Privacy & Security > Open Anyway (once).

Developer Setup

git clone https://github.com/gustavohenrip/ClaudeCode-Better.git
cd ClaudeCode-Better
./commands/setup.command
./commands/start.command

Command	Description
npm run dev	Development mode with hot reload
npm run dist	Package macOS .app
npm run dist:win	Package Windows .exe (NSIS, x64)
npm run doctor	Environment diagnostic

Prerequisites

macOS 13+ or Windows 10+. Install in order:

1. Xcode CLT (macOS): xcode-select --install
2. Node.js 20.x or 22.x: brew install node
3. Python setuptools (3.12+): python3 -m pip install --upgrade pip setuptools
4. Claude Code CLI: npm install -g @anthropic-ai/claude-code
5. Authenticate: claude
6. Whisper (macOS, for voice): brew install whisper-cli

No API keys or .env required. Uses your existing Claude Code CLI auth.

Security & Privacy

• No telemetry — zero analytics or tracking
• No cloud dependency — everything goes through your local Claude CLI
• Permission brokering — tool calls intercepted on 127.0.0.1 only, dangerous tools require approval
• Credential isolation — CLAUDECODE env var stripped from subprocesses
• Sensitive masking — tokens, passwords, and API keys masked in the permission UI
• Auto-deny timeout — unanswered permissions denied after 5 minutes

Compatibility

Component	Version
macOS	15.x (Sequoia)
Windows	10+ (x64)
Node.js	20.x, 22.x
Electron	37.x
Claude Code CLI	2.1.71+

Credits

BetterCC is built on top of Clui CC, created by Lucas Couto. The original project laid the entire foundation: the Electron architecture, ControlPlane process management, permission server, streaming pipeline, React renderer, Zustand store, marketplace integration, and voice input system. All credit for the base application goes to him.

This fork by Gustavo Puhlmann adds the diff viewer, reasoning controls, thinking support, token tracking, global rules, MCP management, Windows support, and various bug fixes and optimizations.

License

MIT — Copyright (c) 2025-2026 Lucas Couto. Fork maintained by Gustavo Puhlmann.

---

_{Original project by Lucas Couto. Enhanced by Gustavo Puhlmann.}