weiesky/cc-viewer

CC‑Viewer – a web/desktop UI wrapper for Claude Code

What it is – CC‑Viewer (installed as the ccv command) is a thin wrapper around the Claude Code CLI. It launches Claude Code exactly as you would from the terminal, but simultaneously starts a local web UI (and optional native desktop app) that visualises the session, lets you edit files, search the project, view diffs, and manage approvals. All arguments you would normally pass to claude are forwarded, so you can keep using your existing Claude Code workflow.

Why you might want it – The UI gives you:

• Real‑time view of Claude’s output, code diffs and file changes.
• VS‑Code‑style search‑and‑replace across the whole project (uses ripgrep when available).
• Mobile access via QR code and optional password protection for LAN sharing.
• Per‑model system‑prompt management, letting you inject custom prompts for specific LLMs.
• A logger mode that captures the raw Claude Code API traffic, token usage and agent types for debugging or audit.

Installation

# npm (global)
npm install -g cc-viewer

# Homebrew (macOS / Linux – recommended)
brew tap weiesky/cc-viewer
brew install cc-viewer

# pnpm (global)
pnpm add -g cc-viewer

Basic usage

# Drop‑in replacement for `claude`
ccv                     # interactive mode (opens the web UI automatically)
ccv -c --d             # example: continue previous session and skip permission checks

# Headless / SDK mode (chat from the browser, no terminal panel)
ccv -SDK               # start SDK session
ccv -SDK -c            # continue most recent session
ccv -SDK --model sonnet

Key features

Feature	What it does
Programming mode	Shows Claude’s generated code, diffs, and lets you edit files directly in the browser.
Project‑wide search & replace	Ripgrep‑backed search with regex, case‑sensitive, glob filters; replace preview and apply across files.
Mobile programming	QR code to open the same session on a phone/tablet; optional password login for LAN sharing.
Password protection	--usePassword generates or sets a 6‑character password; stored (base64‑obfuscated) in preferences.json.
Model‑specific system prompts	UI to create/override system‑prompt files per model (global or workspace scope); includes built‑in prompts for several popular models.
Logger mode	Captures every Claude Code API request, shows token stats, differentiates Main‑Agent vs Sub‑Agent calls, and visualises body diffs.
Session logging	From v1.7.0 logs are stored per‑session in a compact wire‑format; migration commands (ccv convert, ccv verify) handle older .jsonl logs.
Desktop app	Pre‑built binaries are available on the GitHub releases page.

Configuration – The UI lets you pick which Claude executable to use (auto‑detects from PATH, CodeFuse, npm, etc.). The chosen path is saved in ~/.claude/cc-viewer/preferences.json. Global settings, auth tokens, and system‑prompt files live under the same directory.

Troubleshooting tip – If ccv fails to start, open Claude Code, run the instruction:

I have installed the cc-viewer npm package, but running ccv still doesn't work properly. Check cc-viewer's cli.js and findcc.js and adapt them to the local Claude Code deployment based on the specific environment. Keep the scope of changes confined to findcc.js as much as possible.

Claude Code will patch findcc.js automatically.

License – MIT.

---

CC‑Viewer is a genuine open‑source utility that augments the Anthropic Claude Code developer assistant with a rich, shareable UI and logging capabilities.