cc-viewer 1.2.3 → 1.2.7

package/README.md

@@ -1,24 +1,43 @@
 # CC-Viewer
 
-A request monitoring system for Claude Code that captures and visualizes all API requests and responses in real time. Helps developers monitor their Context for reviewing and debugging during Vibe Coding.
+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.
 
-[简体中文](./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)
+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)
 
 ## Usage
 
+### Installation
+
 ```bash
 npm install -g cc-viewer
 ```
 
-After installation, run:
+### Run & Auto-Configuration
 
 ```bash
 ccv
 ```
 
-Then use Claude Code as usual and open `http://localhost:7008` in your browser to view the monitoring interface.
+This command automatically detects your local Claude Code installation method (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.
+
+### 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.
+
+### 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`.
+
+Once configured, just use the `claude` command as usual. Visit `http://localhost:7008` to view the monitoring interface.
+
+### Troubleshooting
 
-After Claude Code updates, no manual action is needed — the next time you run `claude`, it will automatically detect and reconfigure.
+- **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.
 
 ### Uninstall
 
@@ -26,80 +45,58 @@ After Claude Code updates, no manual action is needed — the next time you run
 ccv --uninstall
 ```
 
+### Check Version
+
+```bash
+ccv --version
+```
+
 ## Features
 
 ### Request Monitoring (Raw Mode)
-
-- Real-time capture of all API requests from Claude Code, including streaming responses
-- Left panel shows request method, URL, duration, and status code
-- Automatically identifies and labels Main Agent and Sub Agent requests (with sub-types: Bash, Task, Plan, General)
-- Request list auto-scrolls to the selected item (centered on mode switch, nearest on manual click)
-- Right panel supports Request / Response tab switching
-- Request Body expands `messages`, `system`, `tools` one level by default
-- Response Body fully expanded by default
-- Toggle between JSON view and plain text view
-- One-click JSON content copy
+<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)
-- Diff section supports JSON/Text view switching and one-click copy
-- "Expand Diff" setting: when enabled, MainAgent requests auto-expand the diff section
-- Body Diff JSON tooltip is dismissible; once closed, the preference is persisted server-side and never shown again
-- Sensitive headers (`x-api-key`, `authorization`) are automatically masked in JSONL log files to prevent credential leakage
 - 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
 
 ### Chat Mode
 
-Click the "Chat mode" button in the top right to parse Main Agent's full conversation history into a chat interface:
-
-- User messages right-aligned (blue bubbles), Main Agent replies left-aligned (dark bubbles) with Markdown rendering
-- `/compact` messages auto-detected and displayed collapsed, click to expand full summary
-- Tool call results displayed inline within the corresponding Assistant message
-- `thinking` blocks collapsed by default, rendered as Markdown, click to expand; supports one-click translation
-- `tool_use` shown as compact tool call cards (Bash, Read, Edit, Write, Glob, Grep, Task each have dedicated displays)
-- Task (SubAgent) tool results rendered as Markdown
-- User selection messages (AskUserQuestion) shown in Q&A format
-- System tags (`<system-reminder>`, `<project-reminder>`, etc.) auto-collapsed
-- Skill loaded messages auto-detected and collapsed, showing skill name; click to expand full documentation with Markdown rendering
-- Skills reminder auto-detected and collapsed
-- System text auto-filtered, showing only real user input
-- Multi-session segmented display (auto-segmented after `/compact`, `/clear`, etc.)
-- Each message shows a timestamp accurate to the second, derived from API request timing
-- Each message has a "View Request" link to jump back to raw mode at the corresponding API request
-- Bidirectional mode sync: switching to chat mode scrolls to the conversation matching the selected request; switching back scrolls to the selected request
-- Settings panel: toggle default collapse state for tool results and thinking blocks
-- Global settings: toggle filtering of irrelevant requests (count_tokens, heartbeat) from the request list
+Click the "Chat Mode" button in the top right to parse 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" />
 
-### Translation
 
-- Thinking blocks and assistant messages support one-click translation
-- Powered by Claude Haiku API, uses `x-api-key` authentication only (OAuth session tokens are excluded to prevent context pollution)
-- Automatically captures haiku model name from mainAgent requests; defaults to `claude-haiku-4-5-20251001`
-- Translation results are cached; click again to toggle back to the original text
-- Loading spinner animation shown during translation
-- (?) help icon on `authorization` header links to concept doc explaining context pollution
+- 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
+
 
-### Token Stats
+### Statistics Tool
 
-Hover panel in the header area:
+"Data Statistics" hover panel in the header area:
+<img width="1500" height="729" alt="image" src="https://github.com/user-attachments/assets/b23f9a81-fc3d-4937-9700-e70d84e4e5ce" />
 
-- Token counts grouped by model (input/output)
-- Cache creation/read counts and cache hit rate
-- Cache rebuild statistics: grouped by reason (TTL, system/tools/model change, message truncation/modification, key change) with count and cache_creation tokens
-- Tool usage statistics: call counts per tool, sorted by frequency
-- Skill usage statistics: call counts per skill, sorted by frequency
+- 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
-- Main Agent cache expiration countdown
 
 ### Log Management
 
 Via the CC-Viewer dropdown menu in the top left:
+<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 new window
-- Load local JSONL file: directly select and load a local `.jsonl` file (up to 500MB)
-- Download current log: download the current monitoring JSONL log file
+- 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)
+- 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
-- Export user prompts: extract and display all user inputs with three view modes — Original (raw content), Context (with system tags collapsible), and Text (plain text only); slash commands (`/model`, `/context`, etc.) shown as standalone entries; command-related tags auto-hidden from prompt content
-- Export prompts to TXT: export user prompts (text only, excluding system tags) to a local `.txt` file
+- 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 `.txt` file
 
 ### Multi-language Support
 

package/cli.js

@@ -3,8 +3,8 @@
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
+import { spawn, execSync } from 'node:child_process';
 import { t } from './i18n.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -65,7 +65,21 @@ function getShellConfigPath() {
   return resolve(homedir(), '.zshrc');
 }
 
-function buildShellHook() {
+function buildShellHook(isNative) {
+  if (isNative) {
+    return `${SHELL_HOOK_START}
+claude() {
+  # Avoid recursion if ccv invokes claude
+  if [ "$1" = "--ccv-internal" ]; then
+    shift
+    command claude "$@"
+    return
+  fi
+  ccv run -- claude --ccv-internal "$@"
+}
+${SHELL_HOOK_END}`;
+  }
+
   return `${SHELL_HOOK_START}
 claude() {
   local cli_js=""
@@ -83,14 +97,23 @@ claude() {
 ${SHELL_HOOK_END}`;
 }
 
-function installShellHook() {
+function installShellHook(isNative) {
   const configPath = getShellConfigPath();
   try {
-    const content = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : '';
+    let content = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : '';
+
     if (content.includes(SHELL_HOOK_START)) {
-      return { path: configPath, status: 'exists' };
+      // Check if existing hook matches desired mode
+      const isNativeHook = content.includes('ccv run -- claude');
+      if (!!isNative === !!isNativeHook) {
+        return { path: configPath, status: 'exists' };
+      }
+      // Mismatch: remove old hook first
+      removeShellHook();
+      content = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : '';
     }
-    const hook = buildShellHook();
+
+    const hook = buildShellHook(isNative);
     const newContent = content.endsWith('\n') ? content + '\n' + hook + '\n' : content + '\n\n' + hook + '\n';
     writeFileSync(configPath, newContent);
     return { path: configPath, status: 'installed' };
@@ -138,25 +161,166 @@ 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
+    const { startProxy } = await import('./proxy.js');
+    const proxyPort = await startProxy();
+
+    // args = ['run', '--', 'command', 'claude', ...] or ['run', 'claude', ...]
+    // Our hook uses: ccv run -- claude --ccv-internal "$@"
+    // args[0] is 'run'.
+    // If args[1] is '--', then command starts at args[2].
+
+    let cmdStartIndex = 1;
+    if (args[1] === '--') {
+      cmdStartIndex = 2;
+    }
+
+    let cmd = args[cmdStartIndex];
+    if (!cmd) {
+      console.error('No command provided to run.');
+      process.exit(1);
+    }
+    let cmdArgs = args.slice(cmdStartIndex + 1);
+
+    // If cmd is 'claude' and next arg is '--ccv-internal', remove it
+    // and we must use 'command claude' to avoid infinite recursion of the shell function?
+    // Node spawn doesn't use shell functions, so 'claude' should resolve to the binary in PATH.
+    // BUT, if 'claude' is a function in the current shell, spawn won't see it unless we use shell:true.
+    // We are using shell:false (default).
+    // So spawn('claude') should find /usr/local/bin/claude (the binary).
+    // The issue might be that ccv itself is running in a way that PATH is weird?
+
+    // Wait, the shell hook adds '--ccv-internal'. We should strip it before spawning.
+    if (cmdArgs[0] === '--ccv-internal') {
+      cmdArgs.shift();
+    }
+
+    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();
+      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) => {
+      process.exit(code);
+    });
+
+    child.on('error', (err) => {
+      console.error('Failed to start command:', err);
+      process.exit(1);
+    });
+  } catch (err) {
+    console.error('Proxy error:', err);
+    process.exit(1);
+  }
+}
+
 // === 主逻辑 ===
 
-const isUninstall = process.argv.includes('--uninstall');
-const isVersion = process.argv.includes('--v') || process.argv.includes('--version');
+const args = process.argv.slice(2);
+const isUninstall = args.includes('--uninstall');
+const isHelp = args.includes('--help') || args.includes('-h') || args[0] === 'help';
+const isVersion = args.includes('--v') || args.includes('--version') || args.includes('-v');
+
+if (isHelp) {
+  console.log(t('cli.help'));
+  process.exit(0);
+}
 
 if (isVersion) {
-  const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'));
-  console.log(`cc-viewer v${pkg.version}`);
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'));
+    console.log(`cc-viewer v${pkg.version}`);
+  } catch (e) {
+    console.error('Failed to read version:', e.message);
+  }
   process.exit(0);
 }
 
-if (isUninstall) {
+if (args[0] === 'run') {
+  runProxyCommand(args);
+} else if (args.includes('--uninstall')) {
   const cliResult = removeCliJsInjection();
   const shellResult = removeShellHook();
 
   if (cliResult === 'removed' || cliResult === 'clean') {
     console.log(t('cli.uninstall.cliCleaned'));
   } else if (cliResult === 'not_found') {
-    console.log(t('cli.uninstall.cliNotFound'));
+    // console.log(t('cli.uninstall.cliNotFound'));
+    // Silent is better for mixed mode uninstall
   } else {
     console.log(t('cli.uninstall.cliFail'));
   }
@@ -171,36 +335,72 @@ if (isUninstall) {
 
   console.log(t('cli.uninstall.done'));
   process.exit(0);
-}
-
-// 正常安装流程
-try {
-  const cliResult = injectCliJs();
-  const shellResult = installShellHook();
-
-  if (cliResult === 'exists' && shellResult.status === 'exists') {
-    console.log(t('cli.alreadyWorking'));
+} else {
+  // Installation Logic
+  let mode = 'unknown';
+  if (existsSync(cliPath)) {
+    mode = 'npm';
   } else {
-    if (cliResult === 'exists') {
-      console.log(t('cli.inject.exists'));
-    } else {
-      console.log(t('cli.inject.success'));
-    }
-
-    if (shellResult.status === 'installed') {
-      console.log('All READY!');
-    } else if (shellResult.status !== 'exists') {
-      console.log(t('cli.hook.fail', { error: shellResult.error }));
+    const nativePath = getNativeInstallPath();
+    if (nativePath) {
+      mode = 'native';
     }
   }
 
-  console.log(t('cli.usage.hint'));
-} catch (err) {
-  if (err.code === 'ENOENT') {
+  if (mode === 'unknown') {
     console.error(t('cli.inject.notFound', { path: cliPath }));
-    console.error(t('cli.inject.notFoundHint'));
+    console.error('Also could not find native "claude" command in PATH.');
+    console.error('Please make sure @anthropic-ai/claude-code is installed.');
+    process.exit(1);
+  }
+
+  if (mode === 'npm') {
+    try {
+      const cliResult = injectCliJs();
+      const shellResult = installShellHook(false);
+
+      if (cliResult === 'exists' && shellResult.status === 'exists') {
+        console.log(t('cli.alreadyWorking'));
+      } else {
+        if (cliResult === 'exists') {
+          console.log(t('cli.inject.exists'));
+        } else {
+          console.log(t('cli.inject.success'));
+        }
+
+        if (shellResult.status === 'installed') {
+          console.log('All READY!');
+        } else if (shellResult.status !== 'exists') {
+          console.log(t('cli.hook.fail', { error: shellResult.error }));
+        }
+      }
+      console.log(t('cli.usage.hint'));
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        console.error(t('cli.inject.notFound', { path: cliPath }));
+        console.error(t('cli.inject.notFoundHint'));
+      } else {
+        console.error(t('cli.inject.fail', { error: err.message }));
+      }
+      process.exit(1);
+    }
   } else {
-    console.error(t('cli.inject.fail', { error: err.message }));
+    // Native Mode
+    try {
+      console.log('Detected Claude Code Native Install.');
+      const shellResult = installShellHook(true);
+
+      if (shellResult.status === 'exists') {
+        console.log(t('cli.alreadyWorking'));
+      } else if (shellResult.status === 'installed') {
+        console.log('Native Hook Installed! All READY!');
+      } else {
+        console.log(t('cli.hook.fail', { error: shellResult.error }));
+      }
+      console.log(t('cli.usage.hint'));
+    } catch (err) {
+      console.error('Failed to install native hook:', err);
+      process.exit(1);
+    }
   }
-  process.exit(1);
 }