{"id":47424765,"url":"https://github.com/lcoutodemos/clui-cc","last_synced_at":"2026-03-23T18:01:05.338Z","repository":{"id":344720914,"uuid":"1182790403","full_name":"lcoutodemos/clui-cc","owner":"lcoutodemos","description":"Clui CC — Command Line User Interface for Claude Code","archived":false,"fork":false,"pushed_at":"2026-03-16T03:45:00.000Z","size":341,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-16T13:08:38.907Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lcoutodemos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-16T00:42:18.000Z","updated_at":"2026-03-16T03:45:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lcoutodemos/clui-cc","commit_stats":null,"previous_names":["lcoutodemos/clui-cc"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lcoutodemos/clui-cc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcoutodemos%2Fclui-cc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcoutodemos%2Fclui-cc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcoutodemos%2Fclui-cc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcoutodemos%2Fclui-cc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lcoutodemos","download_url":"https://codeload.github.com/lcoutodemos/clui-cc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lcoutodemos%2Fclui-cc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30864516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-23T14:38:03.667Z","status":"ssl_error","status_checked_at":"2026-03-23T14:38:01.683Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-21T22:00:50.841Z","updated_at":"2026-03-23T18:01:05.325Z","avatar_url":"https://github.com/lcoutodemos.png","language":"TypeScript","funding_links":[],"categories":["🖥️ Clients \u0026 GUIs","TypeScript"],"sub_categories":[],"readme":"# Clui CC — Command Line User Interface for Claude Code\n\nA lightweight, transparent desktop overlay for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) on macOS. Clui CC wraps the Claude Code CLI in a floating pill interface with multi-tab sessions, a permission approval UI, voice input, and a skills marketplace.\n\n## Demo\n\n[![Watch the demo](https://img.youtube.com/vi/NqRBIpaA4Fk/maxresdefault.jpg)](https://www.youtube.com/watch?v=NqRBIpaA4Fk)\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://www.youtube.com/watch?v=NqRBIpaA4Fk\"\u003e▶ Watch the full demo on YouTube\u003c/a\u003e\u003c/p\u003e\n\n## Features\n\n- **Floating overlay** — transparent, click-through window that stays on top. Toggle with `⌥ + Space` (fallback: `Cmd+Shift+K`).\n- **Multi-tab sessions** — each tab spawns its own `claude -p` process with independent session state.\n- **Permission approval UI** — intercepts tool calls via PreToolUse HTTP hooks so you can review and approve/deny from the UI.\n- **Conversation history** — browse and resume past Claude Code sessions.\n- **Skills marketplace** — install plugins from Anthropic's GitHub repos without leaving Clui CC.\n- **Voice input** — local speech-to-text via Whisper (required, installed automatically).\n- **File \u0026 screenshot attachments** — paste images or attach files directly.\n- **Dual theme** — dark/light mode with system-follow option.\n\n## Why Clui CC\n\n- **Claude Code, but visual** — keep CLI power while getting a fast desktop UX for approvals, history, and multitasking.\n- **Human-in-the-loop safety** — tool calls are reviewed and approved in-app before execution.\n- **Session-native workflow** — each tab runs an independent Claude session you can resume later.\n- **Local-first** — everything runs through your local Claude CLI. No telemetry, no cloud dependency.\n\n## How It Works\n\n```\nUI prompt → Main process spawns claude -p → NDJSON stream → live render\n                                         → tool call? → permission UI → approve/deny\n```\n\nSee [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full deep-dive.\n\n## Install App (Recommended)\n\nThe fastest way to get Clui CC running as a regular Mac app. This installs dependencies, voice support (Whisper), builds the app, copies it to `/Applications`, and launches it.\n\n**1) Clone the repo**\n\n```bash\ngit clone https://github.com/lcoutodemos/clui-cc.git\n```\n\n**2) Double-click `install-app.command`**\n\nOpen the `clui-cc` folder in Finder and double-click `install-app.command`.\n\n\u003e **First launch:** macOS may block the app because it's unsigned. Go to **System Settings → Privacy \u0026 Security → Open Anyway**. You only need to do this once.\n\u003e **Folder cleanup:** the installer removes temporary `dist/` and `release/` folders after a successful install to keep the repo tidy.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/shortcut.png\" width=\"520\" alt=\"Press Option + Space to show or hide Clui CC\" /\u003e\u003c/p\u003e\n\nAfter the initial install, just open **Clui CC** from your Applications folder or Spotlight.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTerminal / Developer Commands\u003c/strong\u003e\u003c/summary\u003e\n\nOnly `install-app.command` is kept at root intentionally for non-technical users. Developer scripts live in `commands/`.\n\n### Quick Start (Terminal)\n\n```bash\ngit clone https://github.com/lcoutodemos/clui-cc.git\n```\n\n```bash\ncd clui-cc\n```\n\n```bash\n./commands/setup.command\n```\n\n```bash\n./commands/start.command\n```\n\n\u003e Press **⌥ + Space** to show/hide the overlay. If your macOS input source claims that combo, use **Cmd+Shift+K**.\n\nTo stop:\n\n```bash\n./commands/stop.command\n```\n\n### Developer Workflow\n\n```bash\nnpm install\n```\n\n```bash\nnpm run dev\n```\n\nRenderer changes update instantly. Main-process changes require restarting `npm run dev`.\n\n### Other Commands\n\n| Command | Purpose |\n|---------|---------|\n| `./commands/setup.command` | Environment check + install dependencies |\n| `./commands/start.command` | Build and launch from source |\n| `./commands/stop.command` | Stop all Clui CC processes |\n| `npm run build` | Production build (no packaging) |\n| `npm run dist` | Package as macOS `.app` into `release/` |\n| `npm run doctor` | Run environment diagnostic |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSetup Prerequisites (Detailed)\u003c/strong\u003e\u003c/summary\u003e\n\nYou need **macOS 13+**. Then install these one at a time — copy each command and paste it into Terminal.\n\n**Step 1.** Install Xcode Command Line Tools (needed to compile native modules):\n\n```bash\nxcode-select --install\n```\n\n**Step 2.** Install Node.js (recommended: current LTS such as 20 or 22; minimum supported: 18). Download from [nodejs.org](https://nodejs.org), or use Homebrew:\n\n```bash\nbrew install node\n```\n\nVerify it's on your PATH:\n\n```bash\nnode --version\n```\n\n**Step 3.** Make sure Python has `setuptools` (needed by the native module compiler). On Python 3.12+ this is missing by default:\n\n```bash\npython3 -m pip install --upgrade pip setuptools\n```\n\n**Step 4.** Install Claude Code CLI:\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\n**Step 5.** Authenticate Claude Code (follow the prompts that appear):\n\n```bash\nclaude\n```\n\n**Step 6.** Install Whisper for voice input:\n\n```bash\n# Apple Silicon (M1/M2/M3/M4) — preferred:\nbrew install whisperkit-cli\n# Apple Silicon fallback, or Intel Mac:\nbrew install whisper-cpp\n```\n\n\u003e **No API keys or `.env` file required.** Clui CC uses your existing Claude Code CLI authentication (Pro/Team/Enterprise subscription).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eArchitecture and Internals\u003c/strong\u003e\u003c/summary\u003e\n\n### Project Structure\n\n```\nsrc/\n├── main/                   # Electron main process\n│   ├── claude/             # ControlPlane, RunManager, EventNormalizer\n│   ├── hooks/              # PermissionServer (PreToolUse HTTP hooks)\n│   ├── marketplace/        # Plugin catalog fetching + install\n│   ├── skills/             # Skill auto-installer\n│   └── index.ts            # Window creation, IPC handlers, tray\n├── renderer/               # React frontend\n│   ├── components/         # TabStrip, ConversationView, InputBar, etc.\n│   ├── stores/             # Zustand session store\n│   ├── hooks/              # Event listeners, health reconciliation\n│   └── theme.ts            # Dual palette + CSS custom properties\n├── preload/                # Secure IPC bridge (window.clui API)\n└── shared/                 # Canonical types, IPC channel definitions\n```\n\n### How It Works\n\n1. Each tab creates a `claude -p --output-format stream-json` subprocess.\n2. NDJSON events are parsed by `RunManager` and normalized by `EventNormalizer`.\n3. `ControlPlane` manages tab lifecycle (connecting → idle → running → completed/failed/dead).\n4. Tool permission requests arrive via HTTP hooks to `PermissionServer` (localhost only).\n5. The renderer polls backend health every 1.5s and reconciles tab state.\n6. Sessions are resumed with `--resume \u003csession-id\u003e` for continuity.\n\n### Network Behavior\n\nClui CC operates almost entirely offline. The only outbound network calls are:\n\n| Endpoint | Purpose | Required |\n|----------|---------|----------|\n| `raw.githubusercontent.com/anthropics/*` | Marketplace catalog (cached 5 min) | No — graceful fallback |\n| `api.github.com/repos/anthropics/*/tarball/*` | Skill auto-install on startup | No — skipped on failure |\n\nNo telemetry, analytics, or auto-update mechanisms. All core Claude Code interaction goes through the local CLI.\n\n\u003c/details\u003e\n\n## Troubleshooting\n\nFor setup issues and recovery commands, see [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).\n\nQuick self-check:\n\n```bash\nnpm run doctor\n```\n\n## Tested On\n\n| Component | Version |\n|-----------|---------|\n| macOS | 15.x (Sequoia) |\n| Node.js | 20.x LTS, 22.x |\n| Python | 3.12 (with setuptools installed) |\n| Electron | 33.x |\n| Claude Code CLI | 2.1.71 |\n\n## Known Limitations\n\n- **macOS only** — transparent overlay, tray icon, and node-pty are macOS-specific. Windows/Linux support is not currently implemented.\n- **Requires Claude Code CLI** — Clui CC is a UI layer, not a standalone AI client. You need an authenticated `claude` CLI.\n- **Permission mode** — uses `--permission-mode default`. The PTY interactive transport is legacy and disabled by default.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcoutodemos%2Fclui-cc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flcoutodemos%2Fclui-cc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcoutodemos%2Fclui-cc/lists"}