A Claude Code request monitoring system that captures and visualizes all API requests and responses from Claude Code in real time (raw text, unredacted). Helps developers monitor their context for review and troubleshooting during Vibe Coding sessions.
English | 简体中文 | 繁體中文 | 한국어 | 日本語 | Deutsch | Español | Français | Italiano | Dansk | Polski | Русский | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська
npm install -g cc-viewerccvThis command automatically detects how Claude Code is installed locally (NPM or Native Install) and adapts accordingly.
- NPM Install: Automatically injects an interceptor script into Claude Code's
cli.js. - Native Install: Automatically detects the
claudebinary, configures a local transparent proxy, and sets up a Zsh Shell Hook to forward traffic automatically.
If you need to use a custom API endpoint (e.g., a corporate proxy), simply configure it in ~/.claude/settings.json or set the ANTHROPIC_BASE_URL environment variable. ccv will automatically detect and correctly forward requests.
By default, ccv runs in silent mode when wrapping claude, keeping your terminal output clean and consistent with the native experience. All logs are captured in the background and can be viewed at http://localhost:7008.
Once configured, use the claude command as normal. Visit http://localhost:7008 to access the monitoring interface.
If you encounter issues starting cc-viewer, here is the ultimate troubleshooting approach:
Step 1: Open Claude Code in any directory.
Step 2: Give Claude Code the following instruction:
I have installed the cc-viewer npm package, but after running ccv it still doesn't work properly. Please 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 as constrained as possible within findcc.js.
Letting Claude Code diagnose the issue itself is more effective than asking anyone or reading any documentation!
After the above instruction is completed, findcc.js will be updated. If your project frequently requires local deployment, or if forked code often needs to resolve installation issues, keeping this file lets you simply copy it next time. At this stage, many projects and companies using Claude Code are not deploying on Mac but rather on server-side hosted environments, so the author has separated findcc.js to make it easier to track cc-viewer source code updates going forward.
ccv --uninstallccv --version
- Captures all API requests made by Claude Code in real time, ensuring raw content rather than truncated logs (this is important!!!)
- Automatically identifies and labels Main Agent and Sub Agent requests (subtypes: Bash, Task, Plan, General)
- MainAgent requests support Body Diff JSON, showing a collapsed diff of changes from the previous MainAgent request (only changed/added fields)
- Inline token usage stats per request (input/output tokens, cache creation/read, hit rate)
- Compatible with Claude Code Router (CCR) and other proxy scenarios — falls back to API path pattern matching
Click the "Conversation Mode" button in the top-right corner to parse the Main Agent's full conversation history into a chat interface:
- Agent Team display is not yet supported
- User messages are right-aligned (blue bubbles), Main Agent replies are left-aligned (dark bubbles)
thinkingblocks are collapsed by default, rendered in Markdown, and can be expanded to view the reasoning process; one-click translation is supported (feature is still unstable)- User selection messages (AskUserQuestion) are displayed in a Q&A format
- Bidirectional mode sync: switching to Conversation Mode automatically navigates to the conversation corresponding to the selected request; switching back to Raw Mode automatically navigates to the selected request
- Settings panel: toggle the default collapsed state of tool results and thinking blocks
The "Data Statistics" floating panel in the header area:
- Displays cache creation/read counts and cache hit rate
- Cache rebuild statistics: grouped by reason (TTL, system/tools/model changes, message truncation/modification, key changes) showing counts and cache_creation tokens
- Tool usage statistics: displays call frequency for each tool sorted by number of calls
- Skill usage statistics: displays call frequency for each skill sorted by number of calls
- Concept help (?) icon: click to view built-in documentation for MainAgent, CacheRebuild, and each tool
Via the CC-Viewer dropdown menu in the top-left corner:
- Import local logs: browse historical log files grouped by project, open in a new window
- Load local JSONL file: directly select a local
.jsonlfile to load and view (supports up to 500MB) - Save current log as: download the current monitoring JSONL log file
- Merge logs: combine multiple JSONL log files into a single session for unified analysis
- View user Prompts: extract and display all user inputs, supporting three view modes — Raw mode (original content), Context mode (system tags collapsible), Text mode (plain text); slash commands (
/model,/context, etc.) shown as standalone entries; command-related tags are auto-hidden from Prompt content - Export Prompts to TXT: export user Prompts (plain text, excluding system tags) to a local
.txtfile
CC-Viewer supports 18 languages, automatically switching based on system locale:
简体中文 | English | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська
CC-Viewer automatically checks for updates on startup (at most once every 4 hours). Within the same major version (e.g., 1.x.x → 1.y.z), updates are applied automatically and take effect on the next restart. Cross-major-version updates only show a notification.
Auto-update follows Claude Code's global configuration in ~/.claude/settings.json. If Claude Code has auto-updates disabled (autoUpdates: false), CC-Viewer will also skip auto-updates.
MIT