ccgui is an open-source desktop client for AI coding. In plain words: it brings command-line AI coding runtimes such as Claude Code, Codex CLI, Gemini CLI, and OpenCode 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. File and tool activity is visible as it happens; token usage and estimated cost appear when the selected runtime supplies the required metadata.
The app is built with Tauri 2 + React 19 + TypeScript + Rust and runs on macOS, Windows, and Linux. App settings, workspace indexes, and client state are persisted locally by default. Content sent to an AI provider, Browser Agent, email service, or an optional remote/web service follows the boundary of that configured service.
What can ccgui do?
One client, multiple AI engines
- Registers runtime adapters for Claude Code, Codex CLI, Gemini CLI, and OpenCode. Gemini is enabled by default; OpenCode is optional. Their planned retirement remains an active migration, not shipped behavior.
- Claude and Codex support managed provider profiles. Gemini and OpenCode retain the provider/configuration model exposed by their own runtimes.
- Sessions survive restarts: close the app and your conversation history is still there. Resume broken sessions and see how much context each one is using.
A chat box designed for coding
- The input box supports
@file references, slash commands, pasted images, and attachments. - Supported file edits, shell/tool calls, and reads show up as live cards.
- Claude/Codex sessions expose rewind and fork where the current runtime capability supports them.
- Too lazy to type? Use voice dictation. Bad at prompts? The built-in prompt enhancer polishes them for you.
- Queue follow-ups: while the AI is busy, line up your next question.
Not just chat — a full set of dev panels
- File tree: browse, preview, copy, paste, rename, and drag files straight into the conversation.
- Built-in terminal: a real terminal, no need to switch windows.
- Git panel: stage, commit (with AI-generated commit messages), branches, worktrees, diffs, and commit history.
- Global search: files, sessions, past messages, skills, and commands — one search box for everything.
Stay organized when tasks pile up
- Plan panel: the AI's execution plan listed step by step, so you always know where it is.
- Kanban board: drag task cards around to manage your iteration.
- Task Center: inspect Kanban/orchestration task runs, logs, and artifact summaries; retry, resume, cancel, or fork when the run and engine support that action.
- Intent Canvas: sketch your plan on a canvas before writing any code.
Project intelligence (the part that makes ccgui different)
- Project Map: the AI scans your project and builds an interactive knowledge graph — file relations, API contracts, and module dependencies at a glance, with incremental updates.
- Project Memory: store key conventions and lessons, then inject selected memories with
@@or explicitly enable Memory Reference retrieval for the current turn. - Context Ledger: inspect selected or inherited context sources together with available token/character estimates, freshness, and attribution confidence.
- Usage stats: inspect token, cache, and estimated-cost metadata when the runtime provides it. Monthly budget thresholds are local visual guidance; they do not interrupt the runtime.
Extensions and personalization
- Discover and manage available MCP servers and Skills, and enable bundled curated skills. MCP/Plugin marketplace entries are currently Coming Soon.
- Browser Agent: open policy-allowed HTTP(S) pages and collect bounded read-only context. Snapshot/navigation support can degrade by platform; element and form actions are not yet supported.
- 21 built-in VS Code-derived themes, plus user-message color, window transparency, and UI/code font controls.
- The WebView UI ships 10 languages. The native desktop menu is localized for Chinese and English today; other locales fall back to Chinese. Composer, panel, navigation, and file-action shortcuts are configurable.
- macOS / Windows / Linux, with in-app auto-update.
For what changed in each release, see CHANGELOG.md.
Download
Grab the installer for your platform from the Releases page:
| Platform | Installer |
|---|---|
| macOS (Apple Silicon) | aarch64.dmg |
| macOS (Intel) | x64.dmg |
| Windows | .exe (NSIS) |
| Linux | .AppImage |
After installing, configure your AI engine in Settings (e.g. a Claude Code API key or local CLI), add a project folder, and you're good to go.
Getting it running (setup guide)
Want to build it yourself or contribute? Three steps.
Step 1: Prepare your environment
You need these three things:
| Tool | Version | What for |
|---|---|---|
| Node.js | 20 or newer | Runs the frontend |
| Rust | stable (install via rustup) | Compiles the backend |
| CMake | any recent version | Builds some dependencies |
Each OS needs a bit of extra prep (these are Tauri framework requirements — see the official Tauri prerequisites):
- macOS: install Xcode command line tools:
xcode-select --install; get CMake viabrew install cmake. - Windows: install Microsoft C++ Build Tools and WebView2 (Windows 11 ships with WebView2).
- Linux: install
webkit2gtkand friends — just copy the commands from the Tauri docs.
Step 2: Install dependencies
git clone https://github.com/zhukunpenglinyutong/desktop-cc-gui.git
cd desktop-cc-gui
npm installNote: you must use npm. pnpm and yarn are blocked by a script (so everyone gets identical dependency versions).
Step 3: Start it
# macOS / Linux
npm run tauri:dev
# Windows
npm run tauri:dev:winA few tips:
- The first launch compiles the entire Rust backend and can take a few minutes — go grab a coffee. Later launches use incremental builds and are fast.
- An environment self-check (doctor) runs before startup. If it fails, run
npm run doctorby itself — it tells you what's missing and how to install it. - The frontend runs on port
1420. Don't worry if the port is taken; the script cleans it up automatically. - Only touching the UI, not Rust?
npm run devruns the frontend alone in a browser (backend-dependent features won't work there).
Building installers
npm run build:mac-arm64 # macOS Apple Silicon
npm run build:mac-x64 # macOS Intel
npm run build:mac-universal # macOS Universal
npm run build:win-x64 # Windows x64
npm run build:linux-x64 # Linux x64
npm run build:linux-arm64 # Linux arm64How to work on the code (development guide)
Tech stack at a glance
| Part | Technology |
|---|---|
| UI | React 19 + TypeScript + Tailwind CSS 4 |
| Build | Vite 7 |
| Desktop shell | Tauri 2 (Rust backend) |
| Tests | Vitest (frontend) + cargo test (Rust) |
Directory layout
desktop-cc-gui/
├── src/ # Frontend code
│ ├── features/ # ★ Feature modules (50+), one folder per feature — where most work happens
│ │ ├── composer/ # Input box
│ │ ├── messages/ # Message stream
│ │ ├── git/ # Git panel
│ │ ├── project-map/ # Project knowledge map
│ │ └── ... # Each folder is a self-contained feature
│ ├── components/ # Shared UI components used across features
│ ├── services/ # Business logic; services/tauri/* contains frontend↔Rust wrappers
│ ├── i18n/ # 10 shipped WebView locale bundles
│ ├── styles/ # Global styles
│ └── lib/ utils/ # Utility functions
├── src-tauri/ # Rust backend
│ └── src/ # Organized by module: engine / codex / git / terminal / files ...
├── scripts/ # Build, check, and diagnostic scripts
└── docs/ # Architecture docs, performance baselines
The typical workflow for changing a feature
- UI-only change: find the matching module under
src/features/and edit there. New components live inside that feature's own folder. - Needs backend support: add a
#[tauri::command]in the matchingsrc-tauri/src/module, register it insrc-tauri/src/command_registry.rs, and add the frontend wrapper undersrc/services/tauri/<domain>.ts(re-export it fromsrc/services/tauri.tswhen needed). - Changed any UI text: route it through i18n and keep every shipped bundle under
src/i18n/locales/synchronized — hardcoded UI text is not allowed.
Everyday commands
| Command | What it does |
|---|---|
npm run tauri:dev |
Start the full app (dev mode) |
npm run dev |
Frontend only (browser debugging) |
npm run lint |
Code style check |
npm run typecheck |
TypeScript type check |
npm run test |
Run unit tests |
npm run test:watch |
Watch mode (test while you code) |
npm run test:integration |
Full run including heavy integration tests |
Writing tests
- Test files sit next to the source, named
xxx.test.ts/xxx.test.tsx. - The framework is Vitest — it works almost exactly like Jest.
- Heavy integration tests are named
xxx.integration.test.tsx; they're skipped by default and run withnpm run test:integration. - Rust tests go in their modules as usual and run from the repository root with
cargo test --manifest-path src-tauri/Cargo.toml.
Coding rules
Not many rules, but each exists for a reason. Run through them before submitting:
- Run the big three before committing:
npm run lint && npm run typecheck && npm run test— all green before you push. The current CI workflow runs on pushes tomainand by manual dispatch, so local evidence is required before opening a PR. - UI text must go through i18n: every user-visible string comes from
src/i18n/, and every shipped locale bundle must remain synchronized. No hardcoding. - 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. - Prefix CSS classes by feature: e.g. the Git history panel uses
git-history-*class names, so styles from different features don't fight each other. - Respect the large-file policy: new files use an 800-line ratchet and existing areas use 2600/2800/3000-line hard thresholds.
npm run check:large-filesreports;npm run check:large-files:gateis the blocking check. - TypeScript strict mode: don't paper over things with
any; write real types. - Rust file writes go through the shared helper: use the atomic write in
storage.rsinstead of rawwrite, so a crash mid-write can't corrupt user data. - Search before adding a Tauri command:
command_registrymay already have what you need — don't reinvent it. - 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:
feat(composer): 支持粘贴图片转为附件
fix(git): 修复 diff 面板滚动位置丢失
docs(readme): 校准项目文档索引
No emoji in commit messages, and no AI-generated signatures.
Submitting your code (contribution flow)
- Fork the repo and clone it locally.
- Branch off
main, named likefeat/xxxorfix/xxx. - Make your changes and get the big three green locally (
lint/typecheck/test). - Open a PR against this repo's
mainbranch. Title in commit format; in the description, explain what changed, why, and how you verified it. - Attach local verification evidence to the PR. The current CI workflow runs on pushes to
mainand by manual dispatch; do not assume that opening a PR starts it automatically. Medium/high-risk review findings must be fixed before merging.
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 into the project's internals?
- AGENTS.md — the entry point for repository rules (required reading if you develop this project with AI assistance).
- Documentation hub — architecture, performance, plans, research, and dated evidence with explicit truth boundaries.
- .trellis/spec/ — detailed frontend and backend implementation specs.
- OpenSpec workspace — behavior specs, workflow, and governance overview.
- Main capability spec index — all synced mainline behavior contracts.
- Active proposal index — current changes, progress, closure gates, and artifact links.
- Archived proposal index — all archived proposals grouped by month and archive date.
- OpenSpec audit/evidence index — durable references and dated governance snapshots.
License
Friendship Link
Thanks for the support and feedback from the friends at LINUX DO.
Contributors
Thanks to all the contributors who help make ccgui better.
Acknowledgements
- This project originally started from CodexMonitor.
- The Usage Statistics extension module is mainly based on the source code of TokenTracker.
