desktop-cc-gui README

The project's README from github.com/zhukunpenglinyutong/desktop-cc-gui. As one markdown file: README.md.

Desktop CC GUI

ccgui icon

English · 简体中文

zhukunpenglinyutong%2Fdesktop-cc-gui | Trendshift

ccgui is an open-source multi-engine AI coding desktop client. In plain words: it brings command-line AI coding runtimes — Claude Code, Codex CLI, Kimi CLI, Grok CLI, Pi CLI, OMP CLI, and DeepSeek Harness (DSH) — into one graphical interface.

No more staring at a black terminal. Open ccgui, pick a project, and chat with AI to write code, fix bugs, and commit to Git. Streaming output, thinking traces, and tool calls are visible as they happen; token usage appears when the engine reports it.

The app is built with Tauri 2 + React 18 + TypeScript + Rust and runs on macOS, Windows, and Linux. Settings and state are persisted locally. Content sent to an AI provider follows the boundary of the channel you configured for that CLI.

What can ccgui do?

One client, seven AI engines

A chat box designed for coding

Not just chat — a full set of dev panels

Plugin system

Settings, network, and updates

Download

Grab the installer for your platform from the Releases page:

Platform Installer
macOS (Apple Silicon, signed) aarch64.dmg
Windows .exe (NSIS)
Linux .AppImage

After installing, open Settings, configure a provider channel for the CLI you want (or sign in), add a project folder, and start chatting.

Using DeepSeek Harness (DSH)

  1. Install the DSH CLI on your machine and configure its models and API keys in DSH itself — not as a separate vendor preset inside ccgui.
  2. In Settings → DeepSeek Harness, ccgui can adopt a running local dsh web host or auto-start one.
  3. Select DeepSeek Harness in the composer engine picker. Chat runs through DSH's headless profile; models and credentials stay in DSH.

Getting it running (setup guide)

Want to build it yourself or contribute? Three steps.

Step 1: Prepare your environment

Tool Version What for
Node.js 20 or newer Runs the frontend toolchain
pnpm 10 (pinned via packageManager) Installs dependencies
Rust stable (install via rustup) Compiles the backend

Each OS also needs the standard Tauri prerequisites — see the official Tauri guide:

Step 2: Install dependencies

git clone https://github.com/zhukunpenglinyutong/desktop-cc-gui.git
cd desktop-cc-gui
pnpm install

Note: this is a pnpm workspace (the plugin SDK lives in packages/plugin-sdk); the lockfile is pnpm-lock.yaml.

Step 3: Start it

pnpm dev

A few tips:

Building installers

pnpm build:mac                 # macOS signed build (scripts/build-signed-macos.sh)
pnpm build:mac:skip-notarize   # same, skipping notarization

Windows and Linux installers are produced by the CI workflows under .github/workflows/ (release.yml, build-windows-artifact.yml).

How to work on the code (development guide)

Tech stack at a glance

Part Technology
UI React 18 + TypeScript + Tailwind CSS 4 + zustand
Build Vite 6
Desktop shell Tauri 2 (Rust backend: git2, rusqlite, portable-pty, axum)
Tests Vitest (frontend) + cargo test (Rust)

Directory layout

desktop-cc-gui/
├── src/                    # Frontend code
│   ├── features/           # ★ Feature modules: chat / files / git / terminal /
│   │                       #   settings / plugins / commands / update / open-app
│   ├── components/         # Shared UI components (incl. engine brand icons)
│   ├── i18n/               # zh + en locale bundles
│   ├── styles/             # Global styles
│   └── lib/ utils/         # Utility functions
├── src-tauri/              # Rust backend
│   └── src/                # engine/ (one module per CLI), history/, plugins/,
│                           # git.rs, terminal.rs, web.rs (LAN bridge), ...
├── packages/plugin-sdk/    # @ccgui/plugin-sdk — plugin authoring kit
├── tests/                  # Frontend integration-style tests (Vitest)
├── scripts/                # Build and packaging scripts
└── docs/                   # Plugin development guide, engine mode notes

The typical workflow for changing a feature

  1. UI-only change: find the matching module under src/features/ and edit there. New components live inside that feature's own folder.
  2. Needs backend support: add a #[tauri::command] in the matching src-tauri/src/ module and call it from the frontend via the Tauri API.
  3. Changed any UI text: route it through i18n and keep both bundles (src/i18n/zh.ts, src/i18n/en.ts) synchronized — hardcoded UI text is not allowed.

Everyday commands

Command What it does
pnpm dev Start the full app (Tauri dev mode)
pnpm build TypeScript check + frontend production build
pnpm test Run the Vitest suite
pnpm preview Preview the production frontend build
cargo test --manifest-path src-tauri/Cargo.toml Run Rust tests

Writing tests

Coding rules

Not many rules, but each exists for a reason:

  1. Run the big three before opening a PR: pnpm build (typecheck) and pnpm test green locally, plus cargo test if you touched Rust.
  2. UI text must go through i18n: every user-visible string comes from src/i18n/, and both shipped locale bundles must stay synchronized.
  3. Keep components close to home: new components start inside their own feature folder; promote to src/components/ only once they're genuinely reused across features.
  4. TypeScript strict: don't paper over things with any; write real types.
  5. Extend through the plugin SDK where possible: new settings sections and surfaces should register through the same extension points the builtin ones use.
  6. Never commit secrets: API keys and tokens must never appear in code or commit history.

Writing commit messages

Use Conventional Commits with a Chinese action phrase by default: type(scope): 中文动宾短句.

type When to use
feat New feature
fix Bug fix
refactor Refactoring (no behavior change)
docs Documentation
test Adding/updating tests
chore Housekeeping (version bumps, deps, scripts)
perf / style / ci Performance / formatting / CI

Real examples from this repo:

feat(chat): 支持工具调用参数与结果展开、Git Diff/Bash美化及完成元数据展示
fix(codex): Windows .cmd shim 下多行提示词只送达第一行
perf(chat): reveal streamed text per frame without reparsing markdown

No emoji in commit messages, and no AI-generated signatures.

Submitting your code (contribution flow)

  1. Fork the repo and clone it locally.
  2. Branch off main, named like feat/xxx or fix/xxx.
  3. Make your changes and get pnpm build + pnpm test green locally.
  4. Open a PR against this repo's main branch. Title in commit format; in the description, explain what changed, why, and how you verified it.

Not sure where to start? Browse the Issues and pick one that interests you. Found a bug or have an idea? Open an issue and let's talk.

Want to dig deeper?

License

MIT

Thanks for the support and feedback from the friends at LINUX DO.

Contributors

Thanks to all the contributors who help make ccgui better.

Contributors

Acknowledgements

This project originally started from CodexMonitor. Since v1.0.0 the codebase has been rewritten from scratch — no CodexMonitor code remains, but the original inspiration is gratefully acknowledged.

Star History

Star History Chart

desktop-cc-gui (zhukunpenglinyutong/desktop-cc-gui)

Searching Database…

4.5K ·GitHub
Desktop-cc-gui
What is this?ccgui is a desktop GUI that brings command-line AI coding tools (Claude Code, Codex CLI, Kimi CLI, Grok CLI, Pi CLI, OMP CLI and DeepSeek Harness) into one graphical interface, so you can chat with an AI agent to write code, fix bugs and commit to Git instead of staring at a bare terminal.
Is this a coding agent itself, or does it just wrap other CLIs?ccgui doesn't ship its own AI engine — it's a Tauri + React desktop shell that registers adapters for existing CLI tools like Claude Code and Codex CLI, letting you pick which engine runs per chat session.
How do I get it running?Grab the prebuilt installer for your OS from the Releases page (macOS .dmg, Windows .exe via NSIS, or Linux .AppImage), then open Settings to configure a provider channel or sign in for the CLI you want to use.
Do I need the AI CLIs installed separately?For most engines, provider channels are written straight into each CLI's own native config files inside ccgui. DeepSeek Harness (DSH) is the exception — you install the DSH CLI yourself and configure its models and API keys there, then ccgui connects to a running or auto-started DSH web host.
Which operating systems does it run on?ccgui ships signed builds for macOS (Apple Silicon), Windows (.exe via NSIS) and Linux (.AppImage).
Where does my chat data and code go?Settings and session state are stored locally on your machine, and whatever you send to an AI provider follows the boundary of the channel you configured for that specific CLI — there's no separate server-side credential store run by ccgui.
What's inside the dev panels besides chat?Alongside the chat composer, ccgui ships a virtualized file tree with Git status colors and a built-in CodeMirror editor, a real PTY-backed terminal (xterm + WebGL), a Git panel for staging, committing and diffing, and a keyboard-driven command palette.
Can I extend ccgui with plugins?Yes — a first-party plugin SDK (@ccgui/plugin-sdk) lets plugins add settings sections and config-driven UI through the same extension points the builtin app uses, without shipping custom frontend code.
Can I access ccgui from another device on my network?Yes, the LAN web access feature serves the UI to other devices over a token-authenticated WebSocket bridge, with a QR code in Settings for quick pairing.
Where did this project come from?ccgui originally started from a project called CodexMonitor, but since v1.0.0 the codebase has been fully rewritten from scratch, keeping only the original inspiration.
What are similar projects?cocode, ai-manager, zuse, acryl, monocode, skills-manager, qwen-code, shipyard
Which topics is it in?vibe-coding, ai-coding, tauri, dsh, harness, deepseek-harness, git, gemini, sdk, coding-agent, rust, codex
Creator
zhukunpenglinyutong
Size
209.6 MB
Stars
4.5K
Updated
CommitOct 15Releasev1.1.4Oct 15
Age
8mo
Commits · 90 Days