cc-viewer 1.2.7 → 1.2.9

package/README.md

@@ -1,6 +1,6 @@
 # CC-Viewer
 
-Claude Code request monitoring system that captures and visualizes all API requests and responses from Claude Code in real time (raw text, untruncated). Helps developers monitor their Context for reviewing and troubleshooting during Vibe Coding.
+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 | [简体中文](./docs/README.zh.md) | [繁體中文](./docs/README.zh-TW.md) | [한국어](./docs/README.ko.md) | [日本語](./docs/README.ja.md) | [Deutsch](./docs/README.de.md) | [Español](./docs/README.es.md) | [Français](./docs/README.fr.md) | [Italiano](./docs/README.it.md) | [Dansk](./docs/README.da.md) | [Polski](./docs/README.pl.md) | [Русский](./docs/README.ru.md) | [العربية](./docs/README.ar.md) | [Norsk](./docs/README.no.md) | [Português (Brasil)](./docs/README.pt-BR.md) | [ไทย](./docs/README.th.md) | [Türkçe](./docs/README.tr.md) | [Українська](./docs/README.uk.md)
 
@@ -12,32 +12,40 @@ English | [简体中文](./docs/README.zh.md) | [繁體中文](./docs/README.zh-
 npm install -g cc-viewer
 ```
 
-### Run & Auto-Configuration
+### Running and Auto-Configuration
 
 ```bash
 ccv
 ```
 
-This command automatically detects your local Claude Code installation method (NPM or Native Install) and adapts accordingly.
+This 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 `claude` binary, configures a local transparent proxy, and sets up a Zsh Shell Hook to automatically forward traffic.
+- **Native Install**: Automatically detects the `claude` binary, configures a local transparent proxy, and sets up a Zsh Shell Hook to forward traffic automatically.
 
 ### Configuration Override
 
-If you need to use a custom API endpoint (e.g., corporate proxy), simply configure it in `~/.claude/settings.json` or set the `ANTHROPIC_BASE_URL` environment variable. `ccv` will automatically detect it and forward requests correctly.
+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.
 
 ### Silent Mode
 
-By default, `ccv` runs in silent mode when wrapping `claude`, ensuring your terminal output stays clean and consistent with the native experience. All logs are captured in the background and can be viewed at `http://localhost:7008`.
+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, just use the `claude` command as usual. Visit `http://localhost:7008` to view the monitoring interface.
+Once configured, use the `claude` command as normal. Visit `http://localhost:7008` to access the monitoring interface.
 
 ### Troubleshooting
 
-- **Mixed Output**: If you see `[CC-Viewer]` debug logs mixed with Claude's output, please update to the latest version (`npm install -g cc-viewer`).
-- **Connection Refused**: Make sure the `ccv` background process is running. Running `ccv` or `claude` (after hook installation) should start it automatically.
-- **Empty Body**: If you see "No Body" in the Viewer, it may be due to non-standard SSE formats. The Viewer now supports capturing raw content as a fallback.
+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.
 
 ### Uninstall
 
@@ -55,44 +63,44 @@ ccv --version
 
 ### Request Monitoring (Raw Mode)
 <img width="1500" height="720" alt="image" src="https://github.com/user-attachments/assets/519dd496-68bd-4e76-84d7-2a3d14ae3f61" />
-- Real-time capture of all API requests from Claude Code, ensuring raw text rather than truncated logs (this is important!!!)
-- Automatically identifies and labels Main Agent and Sub Agent requests (sub-types: Bash, Task, Plan, General)
-- MainAgent requests support Body Diff JSON, showing a collapsible diff with the previous MainAgent request (only changed/added fields)
+- 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 setups — requests are matched by API path pattern as a fallback
+- Compatible with Claude Code Router (CCR) and other proxy scenarios — falls back to API path pattern matching
 
-### Chat Mode
+### Conversation Mode
 
-Click the "Chat Mode" button in the top right to parse Main Agent's full conversation history into a chat interface:
+Click the "Conversation Mode" button in the top-right corner to parse the Main Agent's full conversation history into a chat interface:
 <img width="1500" height="730" alt="image" src="https://github.com/user-attachments/assets/c973f142-748b-403f-b2b7-31a5d81e33e6" />
 
 
 - Agent Team display is not yet supported
 - User messages are right-aligned (blue bubbles), Main Agent replies are left-aligned (dark bubbles)
-- `thinking` blocks are collapsed by default, rendered in Markdown, click to expand and view the thinking process; one-click translation supported (feature is still unstable)
-- User selection messages (AskUserQuestion) are displayed in Q&A format
-- Bidirectional mode sync: switching to Chat Mode auto-scrolls to the conversation corresponding to the selected request; switching back to Raw Mode auto-scrolls to the selected request
-- Settings panel: toggle default collapse state for tool results and thinking blocks
+- `thinking` blocks 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
 
 
 ### Statistics Tool
 
-"Data Statistics" hover panel in the header area:
+The "Data Statistics" floating panel in the header area:
 <img width="1500" height="729" alt="image" src="https://github.com/user-attachments/assets/b23f9a81-fc3d-4937-9700-e70d84e4e5ce" />
 
 - Displays cache creation/read counts and cache hit rate
-- Cache rebuild statistics: grouped by reason (TTL, system/tools/model change, message truncation/modification, key change) showing count and cache_creation tokens
-- Tool usage statistics: tools displayed by call frequency, sorted by count
-- Skill usage statistics: skills displayed by call frequency, sorted by count
-- Concept help (?) icons: click to view built-in documentation for MainAgent, CacheRebuild, and each tool
+- 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
 
 ### Log Management
 
-Via the CC-Viewer dropdown menu in the top left:
+Via the CC-Viewer dropdown menu in the top-left corner:
 <img width="1200" height="672" alt="image" src="https://github.com/user-attachments/assets/8cf24f5b-9450-4790-b781-0cd074cd3b39" />
 
-- Import local logs: browse historical log files, grouped by project, opens in a new window
-- Load local JSONL file: directly select and load a local `.jsonl` file (supports up to 500MB)
+- Import local logs: browse historical log files grouped by project, open in a new window
+- Load local JSONL file: directly select a local `.jsonl` file 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
@@ -107,3 +115,13 @@ CC-Viewer supports 18 languages, automatically switching based on system locale:
 ## License
 
 MIT
+
+### How to Submit a PR
+The author welcomes and encourages PRs from the community.
+
+A few requirements:
+
+When submitting a PR, please tell me what your Prompt was and which model you used to modify the code (PRs made with inferior models will not be accepted);
+If there are UI changes, tell me what functionality was modified on the interface — a screenshot with circles drawn around the changes is recommended;
+Changes to cli.js and interceptor.js will be reviewed very carefully, as I don't want issues in core files to affect everyone's usage;
+Please make sure to verify the functionality locally before submitting — much appreciated!

package/cli.js

@@ -1,58 +1,24 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { spawn, execSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { t } from './i18n.js';
+import { INJECT_IMPORT, resolveCliPath, resolveNativePath, buildShellCandidates } from './findcc.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
 const INJECT_START = '// >>> Start CC Viewer Web Service >>>';
 const INJECT_END = '// <<< Start CC Viewer Web Service <<<';
-const INJECT_IMPORT = "import '../../cc-viewer/interceptor.js';";
 const INJECT_BLOCK = `${INJECT_START}\n${INJECT_IMPORT}\n${INJECT_END}`;
 
 
 const SHELL_HOOK_START = '# >>> CC-Viewer Auto-Inject >>>';
 const SHELL_HOOK_END = '# <<< CC-Viewer Auto-Inject <<<';
 
-// Claude Code cli.js 包名候选列表，按优先级排列
-const CLAUDE_CODE_PACKAGES = [
-  '@anthropic-ai/claude-code',
-  '@ali/claude-code',
-];
-
-function getGlobalNodeModulesDir() {
-  try {
-    return execSync('npm root -g', { encoding: 'utf-8' }).trim();
-  } catch {
-    return null;
-  }
-}
-
-function resolveClaudeCodeCliPath() {
-  // 候选基础目录：__dirname 的上级（适用于常规 npm 安装）+ 全局 node_modules（适用于符号链接安装）
-  const baseDirs = [resolve(__dirname, '..')];
-  const globalRoot = getGlobalNodeModulesDir();
-  if (globalRoot && globalRoot !== resolve(__dirname, '..')) {
-    baseDirs.push(globalRoot);
-  }
-
-  for (const baseDir of baseDirs) {
-    for (const packageName of CLAUDE_CODE_PACKAGES) {
-      const candidate = join(baseDir, packageName, 'cli.js');
-      if (existsSync(candidate)) {
-        return candidate;
-      }
-    }
-  }
-  // 兜底：返回全局目录下的默认路径，便于错误提示
-  return join(globalRoot || resolve(__dirname, '..'), CLAUDE_CODE_PACKAGES[0], 'cli.js');
-}
-
-const cliPath = resolveClaudeCodeCliPath();
+const cliPath = resolveCliPath();
 
 function getShellConfigPath() {
   const shell = process.env.SHELL || '';
@@ -80,10 +46,11 @@ claude() {
 ${SHELL_HOOK_END}`;
   }
 
+  const candidates = buildShellCandidates();
   return `${SHELL_HOOK_START}
 claude() {
   local cli_js=""
-  for candidate in "$HOME/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js" "$HOME/.npm-global/lib/node_modules/@ali/claude-code/cli.js"; do
+  for candidate in ${candidates}; do
     if [ -f "$candidate" ]; then
       cli_js="$candidate"
       break
@@ -161,37 +128,6 @@ function removeCliJsInjection() {
   }
 }
 
-function getNativeInstallPath() {
-  // 1. 尝试 which/command -v（继承当前 process.env PATH）
-  for (const cmd of ['which claude', 'command -v claude']) {
-    try {
-      const result = execSync(cmd, { encoding: 'utf-8', shell: true, env: process.env }).trim();
-      // 排除 shell function 的输出（多行说明不是路径）
-      if (result && !result.includes('\n') && existsSync(result)) {
-        return result;
-      }
-    } catch {
-      // ignore
-    }
-  }
-
-  // 2. 检查常见 native 安装路径
-  const home = homedir();
-  const candidates = [
-    join(home, '.claude', 'local', 'claude'),
-    '/usr/local/bin/claude',
-    join(home, '.local', 'bin', 'claude'),
-    '/opt/homebrew/bin/claude',
-  ];
-  for (const p of candidates) {
-    if (existsSync(p)) {
-      return p;
-    }
-  }
-
-  return null;
-}
-
 async function runProxyCommand(args) {
   try {
     // Dynamic import to avoid side effects when just installing
@@ -229,49 +165,24 @@ async function runProxyCommand(args) {
     }
 
     const env = { ...process.env };
-    // [Debug] Verify hook execution
-    // console.error(`[CC-Viewer] Hook triggered for: ${cmd} ${cmdArgs.join(' ')}`);
-
     // Determine the path to the native 'claude' executable
     if (cmd === 'claude') {
-      const nativePath = getNativeInstallPath();
+      const nativePath = resolveNativePath();
       if (nativePath) {
         cmd = nativePath;
       }
     }
     env.ANTHROPIC_BASE_URL = `http://127.0.0.1:${proxyPort}`;
 
-    // [Debug] Force ANTHROPIC_BASE_URL via process.env is not enough for some reason?
-    // Let's also check if we can pass it via command line args if supported, but claude cli doesn't seem to have a --base-url arg documented.
-    // However, maybe the issue is that 'env' in spawn options isn't overriding what claude internal config has?
-    // Claude Code likely reads from ~/.claude/settings.json which might take precedence over env vars?
-    // No, usually env vars take precedence.
-
-    // [Fix] Check if user has ANTHROPIC_BASE_URL in settings.json and use it in proxy.js
-    // We already do that in proxy.js: getOriginalBaseUrl().
-
-    // [Crucial Fix]
-    // Use --settings JSON argument to force ANTHROPIC_BASE_URL configuration
-    // This is safer and more reliable than env vars which might be ignored.
-
-    // console.error(`[CC-Viewer] Setting ANTHROPIC_BASE_URL to ${env.ANTHROPIC_BASE_URL}`);
-
-    // Construct settings JSON string
-    // Note: We need to be careful with quoting for the shell/spawn.
-    // Since we use spawn without shell, we can pass the JSON string directly as an argument.
     const settingsJson = JSON.stringify({
       env: {
         ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL
       }
     });
 
-    // Inject --settings argument
-    // We put it at the beginning of args to ensure it's picked up
     cmdArgs.unshift(settingsJson);
     cmdArgs.unshift('--settings');
 
-    // Force non-interactive if needed? No, we want interactive.
-
     const child = spawn(cmd, cmdArgs, { stdio: 'inherit', env });
 
     child.on('exit', (code) => {
@@ -312,7 +223,7 @@ if (isVersion) {
 
 if (args[0] === 'run') {
   runProxyCommand(args);
-} else if (args.includes('--uninstall')) {
+} else if (isUninstall) {
   const cliResult = removeCliJsInjection();
   const shellResult = removeShellHook();
 
@@ -338,12 +249,42 @@ if (args[0] === 'run') {
 } else {
   // Installation Logic
   let mode = 'unknown';
-  if (existsSync(cliPath)) {
-    mode = 'npm';
-  } else {
-    const nativePath = getNativeInstallPath();
+
+  // Check PATH to determine priority
+  let prefersNative = true; // default to native if not found in PATH
+  const paths = (process.env.PATH || '').split(':');
+  for (const dir of paths) {
+    if (!dir) continue;
+    const exePath = resolve(dir, 'claude');
+    if (existsSync(exePath)) {
+      try {
+        const real = realpathSync(exePath);
+        if (real.includes('node_modules')) {
+          prefersNative = false;
+        } else {
+          prefersNative = true;
+        }
+        break;
+      } catch (e) {
+        // ignore
+      }
+    }
+  }
+
+  const nativePath = resolveNativePath();
+  const hasNpm = existsSync(cliPath);
+
+  if (prefersNative) {
     if (nativePath) {
       mode = 'native';
+    } else if (hasNpm) {
+      mode = 'npm';
+    }
+  } else {
+    if (hasNpm) {
+      mode = 'npm';
+    } else if (nativePath) {
+      mode = 'native';
     }
   }