A desktop GUI for claude-commander — manage your Claude coding sessions from a native window instead of the terminal TUI. Built with Tauri 2 (Rust backend) and a TypeScript/Vite frontend.
It embeds claude-commander directly (as a library) and drives the same tmux-backed sessions, so it stays in sync with whatever the CLI does.
- Session management — grouped by project / section / section-stack (cycle with
⇄); liveness and unread indicators; rename, restart, kill, delete, and "restart fresh". - Embedded terminals — attach to any session in a real PTY (xterm.js); attaching recreates stopped sessions.
Cmd+Wcloses the active tab. - Project shells — open a plain shell terminal in a project or worktree directory.
- Code review — read-only diff view with inline comments; stage comments and Apply them back to the agent.
- Cascade — merge, resume, and abandon stacked sessions; push a stack.
- Theming — 10 built-in themes plus your own custom themes, with a live-preview picker. See
docs/theming.md. - File explorer (
Cmd+E) — keyboard-driven, nnn-style browser of the active session's repo; open a file to drop an@pathreference into the terminal. - Markdown viewer (
Cmd+M) — distraction-free reader for the active session's repo docs (plans, design docs, READMEs). Opens on the doc the session's branch changed most recently (else README), stays live while the agent keeps writing, and has a fuzzy file picker (/) plus in-repo link navigation. - Command palette (
Cmd/Ctrl+K) — fuzzy-jump to a session or run any command. - Config hot-reload — picks up
claude-commanderconfig changes for multi-instance sync.
brew install --cask genio-learn/tap/cc-guiThe app is unsigned, so macOS quarantines it — but the cask clears the quarantine
flag automatically on install, so it opens straight away. (Homebrew removed the
old --no-quarantine flag in 5.x, with no replacement.) If macOS still reports
the app as "damaged", clear the flag manually:
xattr -dr com.apple.quarantine /Applications/CC-GUI.app. Upgrade later with
brew upgrade --cask cc-gui.
Grab the latest build from Releases:
- macOS (Apple Silicon) —
CC-GUI_<version>_aarch64.dmg(aarch64= ARM64 = Apple Silicon) - Linux —
CC-GUI_<version>_amd64.AppImage(portable, runs on any distro) orCC-GUI_<version>_amd64.deb
The macOS app is unsigned (no Apple Developer certificate), so macOS quarantines it on download and reports it as "damaged and can't be opened." It isn't — that message just means "unsigned and quarantined." Drag CC-GUI.app into /Applications, then clear the quarantine flag:
xattr -cr /Applications/CC-GUI.appThen open it normally. (If the .dmg won't even mount, clear it first: xattr -c ~/Downloads/CC-GUI_*_aarch64.dmg.)
To build from source instead, follow the rest of this guide.
| Requirement | Why | Install |
|---|---|---|
| Rust toolchain | Compiles the Tauri backend | rustup.rs |
| Node.js | Builds the frontend | nodejs.org (or nvm) |
| tmux | claude-commander runs every session in a tmux session |
brew install tmux |
claude CLI |
The default program each session launches | Claude Code |
claude-commander itself is a pinned git dependency — Cargo fetches it automatically, so no separate checkout is required (unless you want to develop against a local copy; see Setup).
git clone git@github.com:genio-learn/CC-GUI.git
cd CC-GUI
npm installThat's it. claude-commander is a pinned git dependency, so Cargo fetches it on the first build — no separate checkout needed.
Developing against a local
claude-commander? Copy.cargo/config.toml.exampleto.cargo/config.toml(gitignored) and place your checkout at../claude-commander. Cargo will then build against your local copy instead of the pinned release. See CONTRIBUTING.md.
Development (hot-reload frontend, runs in a dev window):
npm run tauri devPackaged app (build a real .app and install it to /Applications):
npm run app:installThen launch CC-GUI from Finder / Spotlight / Launchpad like any other app. The first build compiles the Rust backend from scratch and takes a few minutes; later builds are incremental.
| Script | What it does |
|---|---|
npm run tauri dev |
Run the app in development with hot reload. |
npm run app:build |
Build the bundles (.app + .dmg) under src-tauri/target/release/bundle/. |
npm run app:install |
Build and (re)install into /Applications. Idempotent — use it for first install and every update. |
npm run typecheck |
Type-check the frontend (tsc --noEmit). |
- GUI changes →
npm run app:install, then relaunch the app. - Newer
claude-commander→ bump thetaginsrc-tauri/Cargo.tomlto the desired release, runcargo update -p claude-commander(fromsrc-tauri/), thennpm run app:install. Pinning to a tag means you adopt new CC releases deliberately.
After any reinstall, fully quit the running app (Cmd+Q) before relaunching so you pick up the new binary.
Press ? in the app (outside a text input) for the full, always-current list.
| Action | Binding |
|---|---|
| Command palette (jump to session / run command) | Cmd/Ctrl+K |
| Help overlay | ? |
| Close active terminal tab | Cmd+W |
| Jump to terminal tab by number | Cmd+1–Cmd+9 |
| Previous / next terminal tab | Cmd+Opt+← / Cmd+Opt+→ |
| Previous / next session (attaches it) | Cmd+Opt+↑ / Cmd+Opt+↓ |
| Open/close file explorer (active session's repo) | Cmd/Ctrl+E |
| File explorer: move cursor | ↑/↓ or j/k |
File explorer: open folder / reference file as @path |
Enter / → / l |
| File explorer: up to parent / filter / toggle hidden | Backspace / / / . |
| Open/close markdown viewer (on the doc this session changed last, else README) | Cmd/Ctrl+M |
Markdown viewer: fuzzy file picker, changed docs first (↑/↓ pick, Enter opens) |
/ or click the file name |
| Terminal: switch to this session's shell | Ctrl+\ |
| Terminal: cursor to line start / end | Cmd+← / Cmd+→ |
| Terminal: delete to line start | Cmd+Backspace |
| Terminal: newline without submitting | Shift+Enter |
| Terminal: copy selection (auto-clears highlight) | select text |
| Terminal: open a link | Cmd+Click |
| Reorder terminal tabs | drag a tab |
| Split the view into panes (up to 4) | drag a tab into a corner of the terminal area |
| Remove a pane from the split | pane header ✕ |
| Resize split panes | drag a pane border |
| Attach / recreate a session | click its row |
| Full session menu (shell, review, rename, editor, PR, lifecycle) | right-click row |
| New session in a project | + on the project |
| New session: pick the harness (Claude / Codex / OpenCode) | ↓ in the title field, or click the command ▾ button |
| Add-project path: complete to common prefix | Tab |
| Add-project path: pick / drill into a directory | ↑ / ↓, then Enter |
| Add-project path: native folder picker | Browse… |
| Project shell | $ on the project |
| Switch sidebar grouping (Sections / Projects / Status) | GROUP BY control |
| Move a session to a section | drag its row onto a section header (drop on In Progress to unpin) |
| Review: select lines for a comment | click a line (shift-click extends), or click/drag the line numbers |
| Review: move the line cursor (comment without the mouse) | j / k |
| Review: comment the cursor line | Enter or c |
| Save a review comment | Cmd/Ctrl+Enter |
| Review: previous / next file | ↑ / ↓ or Ctrl-P / Ctrl-N |
| Review: toggle a file reviewed (bands the row) | click ○ / ✓ on the file row |
| Review: apply staged comments (press twice to confirm) | Apply button |
| Board: move focus between cards / columns | arrow keys |
| Board: attach the focused card | Enter / Space |
The packaging scripts (app:install) and the login-shell PATH fix are macOS-specific. On a Finder-launched app, macOS provides a minimal PATH; the backend re-derives the full PATH from your login shell at startup so tmux, node, git, etc. resolve inside the app's terminals.
CC-GUI owns its own theming (independent of claude-commander config). Ten themes ship built in, and you can drop your own JSON themes into the app's config folder without rebuilding. Full authoring guide: docs/theming.md.
CC-GUI embeds claude-commander, which reports anonymous feature-usage telemetry so the maintainers can see which features are used. It is on by default and opt-out, identifying itself as cc-gui so GUI usage is distinguishable from the terminal app.
What is sent: the name of each feature used (e.g. review.open), a coarse environment fingerprint (OS, architecture, shell name, terminal colour mode), a non-sensitive config snapshot (theme preset, view mode, which optional features are enabled), the app name + version, and a random, resettable install id.
What is never sent: typed text, prompts, Claude session content, comment bodies, branch/session names, repository paths, or command arguments. The event schema is a fixed set of typed fields with no path that forwards free-form text.
To opt out, either uncheck telemetry (send anonymous usage) in Settings (Cmd/Ctrl+K → "Settings"), set the config flag, or export the standard DO_NOT_TRACK variable:
[telemetry]
enabled = falseSee claude-commander's configuration docs for the full detail (and self-hosting the ingest endpoint).