npm - copilot-tracer - Versions diffs - 1.0.4 → 1.0.6 - Mend

copilot-tracer 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,246 +1,217 @@
 # copilot-tracer
-Real-time tracing and prompt-refinement tool for **GitHub Copilot CLI** and **VS Code Copilot extension**.
+Real-time tracing and prompt-refinement companion for **GitHub Copilot CLI**, **Claude Code**, and **VS Code Copilot extension**.
-Captures every prompt, response, token usage, AI credits, tool calls, skill invocations, and duration — all in one place. It also includes a prompt optimizer that rewrites prompts using role grounding, imperative clarity, output formatting, constraint injection, and noise removal. Works via native **OpenTelemetry (OTLP)** integration built into GitHub Copilot, with an optional ACP proxy mode for live CLI tracing.
+Captures every prompt, response, token usage, AI credits, tool calls, and duration — all in one place. Runs as a background daemon that collects data from all your projects automatically. Includes a web dashboard with project overview and per-project live tracing.
 ---
 ## Features
-- **Zero-intrusion capture** — uses Copilot's built-in OTel support. Set 2 env vars, done.
-- **Works everywhere** — captures both Copilot CLI (`copilot -p "..."`) and VS Code Copilot Chat
-- **Prompt refinement** — rewrites prompts with stronger instructions, clearer outputs, and less noise
-- **Real-time web UI** — live dashboard at `http://localhost:4747` with dark theme
-- **Full prompt & response** — see exactly what you sent and what Copilot replied
-- **Token breakdown** — input, output, cached, reasoning, written tokens per request
+- **Daemon mode** — install once, run forever. Collects traces from all projects automatically
+- **Auto project detection** — detects project from `github.copilot.git.repository` in OTLP spans
+- **Zero-intrusion capture** — uses Copilot's built-in OTel support. Set env vars, done.
+- **Works everywhere** — captures GitHub Copilot CLI, Claude Code, and VS Code Copilot Chat
+- **Dashboard** — overview of all projects with token usage, credits, and session counts
+- **Live tracer** — real-time trace table per project with detail panel
+- **Prompt refinement** — rewrites prompts with stronger instructions and less noise
 - **AI Credits tracking** — matches exactly what Copilot terminal reports (e.g. `2.59 cr`)
-- **Tool call visibility** — see every tool/skill/MCP invoked during a session
-- **ACP proxy mode** — wrap the Copilot CLI to trace live JSON-RPC traffic when needed
 - **Persistent storage** — SQLite at `~/.copilot-tracer/traces.db`, survives restarts
-- **Console + Web UI** — CLI table view or browser dashboard, your choice
 ---
-## Prerequisites
-- Node.js v18+ (tested on v24)
-- GitHub Copilot CLI (`copilot` command available in terminal)
-- VS Code 1.99+ with built-in Copilot (no extension install needed)
----
-## Install
+## Quick Start (one-time setup)
 ```bash
 npm install -g copilot-tracer
+copilot-tracer --setup --daemon
 ```
-Requires Node.js v18+. The `copilot-tracer` command is available globally after install.
-> **Building from source**
-> ```bash
-> git clone https://github.com/chuongnd/copilot-tracer
-> cd copilot-tracer && npm install && npx tsc
-> npm link   # registers global command from local build
-> ```
+This will:
+1. Detect your Copilot CLI and VS Code installation
+2. Patch `~/.zshrc` with OTEL env vars
+3. Patch VS Code `settings.json` with terminal env vars
+4. Enable Claude Code OTLP logs/events and enhanced beta traces
+5. Start the daemon on port 4747
----
-## Setup (one-time)
-Run the auto-setup command. It detects your Copilot CLI and VS Code installation and injects the required config automatically:
+Then apply env vars in your current shell:
 ```bash
-copilot-tracer --setup
+source ~/.zshrc
 ```
-What it does:
-- Detects `copilot` CLI path and version
-- Detects VS Code version and confirms built-in Copilot
-- Patches `~/.zshrc` (or `~/.bashrc`) with OTEL env vars
-- Patches VS Code `settings.json` with `terminal.integrated.env.osx` block
+Restart VS Code once. After that, the daemon collects traces from all your Copilot
+and Claude Code sessions automatically. Claude Code content flags are enabled by
+setup so prompts and responses can be displayed in the local dashboard.
-Example output:
-```
-✅ GitHub Copilot CLI detected — /usr/bin/copilot v1.0.77
-✅ Visual Studio Code detected — 1.131.0 (Built-in Copilot)
-✅ Shell profile patched: .zshrc
-✅ VS Code settings patched
-```
+Open **http://localhost:4747** to see the dashboard.
-Then apply the env vars:
+---
-```bash
-source ~/.zshrc
-```
+## How It Works
-Restart VS Code completely (Cmd+Q, then reopen).
+```
+┌─────────────────────────────────────────────────────────┐
+│  copilot-tracer --daemon (runs once, stays running)      │
+│                                                          │
+│  OTLP Receiver ← Copilot CLI + Claude Code + VS Code                   │
+│  (auto-detects project from github.copilot.git.repository)│
+│                                                          │
+│  SQLite DB → Dashboard + Live Tracer (Socket.io)         │
+└─────────────────────────────────────────────────────────┘
+Copilot CLI / Claude Code / VS Code Copilot Chat
+         │
+         │  OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4747
+         ↓
+   POST /v1/traces and /v1/logs (OpenTelemetry OTLP JSON)
+         │
+         ↓
+   copilot-tracer parses spans and events → tokens, credits, tool calls
+         │
+         ↓
+   SQLite DB (~/.copilot-tracer/traces.db)
+         │
+         ├→ Dashboard: all projects overview
+         └→ Live Tracer: real-time per-project view
+```
 ---
-## Manual Setup (alternative)
+## Usage
-If you prefer to configure manually, add these to `~/.zshrc`:
+### Daemon mode (recommended)
 ```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4747
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
-export COPILOT_OTEL_ENABLED=true
-```
+# First time: setup + start daemon
+copilot-tracer --setup --daemon
-For VS Code, add to `~/Library/Application Support/Code/User/settings.json`:
+# Subsequent starts
+copilot-tracer --daemon
-```json
-"terminal.integrated.env.osx": {
-  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4747",
-  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
-  "COPILOT_OTEL_ENABLED": "true"
-}
+# Custom port
+copilot-tracer --daemon --port 8080
 ```
----
+### Normal mode (legacy)
-## Start Tracer
+Per-session mode with optional ACP proxy for live CLI tracing:
 ```bash
-copilot-tracer --ui web --port 4747 --no-proxy
-```
+# Web UI only (read from DB)
+copilot-tracer --ui web --no-proxy
-Open **http://localhost:4747** — shows "waiting for copilot CLI activity".
----
+# With project path
+copilot-tracer --ui web --no-proxy --project-path /path/to/repo
-## Use Copilot Normally
+# With ACP proxy (wraps copilot CLI)
+copilot-tracer --ui web
+```
-No change to how you use Copilot. Just run as usual:
+### Setup only
 ```bash
-# Copilot CLI
-copilot -p "how to convert microservice to modular" --allow-all-tools
-# Or use Copilot Chat in VS Code
+# Just patch env vars without starting
+copilot-tracer --setup
 ```
-Traces appear instantly in the web UI as each request completes.
 ---
-## How It Works
+## Dashboard
-```
-copilot CLI  /  VS Code Copilot Chat
-         |
-         |  reads OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4747
-         |
-         ↓  POST /v1/traces  (OpenTelemetry OTLP JSON)
-  copilot-tracer OTLP receiver
-         |
-         ↓
-  Parse spans → extract prompt, response, tokens, credits, tool calls
-         |
-         ↓
-  SQLite DB  (~/.copilot-tracer/traces.db)
-         |
-         ↓
-  Web UI (Socket.io real-time)  +  Console table
-```
+Open http://localhost:4747 after starting the daemon.
-Copilot has built-in OpenTelemetry instrumentation. When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, it pushes all trace data to that endpoint automatically — both CLI and VS Code extension.
+- **Summary cards** — total projects, sessions, tokens, credits
+- **Project cards** — each project shows path, session count, tokens, credits, last active
+- **Click a project** → opens live tracer filtered to that project
+<img width="737" height="410" alt="image" src="https://github.com/user-attachments/assets/dc20653b-8774-46b3-9a42-6e7bb934aded" />
 ---
-## Web UI
+## Live Tracer
-Open http://localhost:4747 after starting the tracer.
+Real-time trace table for a specific project.
 **Table columns:**
 | Date/Time | Prompt | AI Credits | Duration | Cached | Written | Reasoning | Skills | Agents | MCPs |
 **Interactive features:**
-- Click any row → detail panel: full prompt, full response, reasoning text, call graph
+- Click any row → detail panel: full prompt, response, reasoning, call graph
 - Click AI Credits → cost breakdown per token type
-- Click Reasoning count → full reasoning text
-- Click Skills / Agents / MCPs pill → filtered call list with input/output/duration
-- Real-time updates via Socket.io — no page refresh needed
-- Dark theme
+- Click Reasoning → full reasoning text
+- Click Skills / Agents / MCPs → filtered call list
+- Real-time updates via Socket.io
+<img width="1504" height="742" alt="image" src="https://github.com/user-attachments/assets/f334108f-c587-4228-8120-7dac2f85f90b" />
+<img width="1061" height="696" alt="image" src="https://github.com/user-attachments/assets/1555d5a2-dbca-4f1d-b102-3d2865dcee68" />
 ---
-## Console UI
+## Prompt Refinement
-```bash
-copilot-tracer --ui console --no-proxy
-```
+The web UI includes a prompt optimizer. Click "Refine Prompt" in the trace detail panel.
-Live updating table in terminal. Same columns as web UI. TOTALS row pinned at top.
+Techniques applied:
+- Role grounding, imperative clarity, output format, chain-of-thought
+- Noise removal, constraint injection, redundancy cleanup
 ---
-## Prompt Refinement
+## CLI Flags
-The web UI exposes `POST /api/refine` to improve a raw prompt before sending it to Copilot.
+| Flag | Description |
+|------|-------------|
+| `--daemon` | Run as background daemon (always-on OTLP receiver) |
+| `--setup` | Auto-detect and configure env vars |
+| `--port <port>` | Web UI port (default: 4747) |
+| `--ui <mode>` | UI mode: console \| web \| both (normal mode only) |
+| `--no-proxy` | Web/console only, no ACP proxy (normal mode only) |
+| `--project-path <path>` | Project source path (normal mode only) |
+| `--session <id>` | Custom session ID (normal mode only) |
+| `--debug` | Verbose logging |
-It currently applies these techniques:
+---
-- **Role grounding** — adds an expert persona when the prompt has none
-- **Imperative clarity** — turns soft phrasing into direct instructions
-- **Output format** — asks for JSON, markdown, bullets, or steps when missing
-- **Reasoning guidance** — adds step-by-step thinking for multi-step tasks
-- **Noise removal** — strips filler like “please”, “could you”, and “I think”
-- **Constraint injection** — adds language, tone, length, and audience constraints
-- **Redundancy cleanup** — removes repeated or conflicting instructions
+## Manual Setup (alternative)
-Example request:
+Add to `~/.zshrc`:
 ```bash
-curl -s http://localhost:4747/api/refine \
-  -H 'content-type: application/json' \
-  -d '{"prompt":"help me write a plan for migrating a monolith"}'
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4747
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+export COPILOT_OTEL_ENABLED=true
+# Claude Code telemetry
+export CLAUDE_CODE_ENABLE_TELEMETRY=1
+export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_TRACES_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+export OTEL_LOG_USER_PROMPTS=1
+export OTEL_LOG_ASSISTANT_RESPONSES=1
 ```
-Response shape:
+Claude Code exports standard OTLP logs/events and optional beta traces. See
+[Anthropic's monitoring documentation](https://code.claude.com/docs/en/monitoring-usage)
+for protocol and content controls.
+For VS Code, add to `~/Library/Application Support/Code/User/settings.json`:
 ```json
-{
-  "ok": true,
-  "optimized": "…",
-  "issues": [],
-  "techniques": [],
-  "origTok": 10,
-  "newTok": 22,
-  "inputSavingPct": 0
+"terminal.integrated.env.osx": {
+  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4747",
+  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
+  "COPILOT_OTEL_ENABLED": "true"
 }
 ```
 ---
-## CLI Flags
-| Flag | Description |
-|------|-------------|
-| `--ui web` | Start web UI (default) |
-| `--ui console` | Start console table UI |
-| `--ui both` | Both web + console |
-| `--port 4747` | Web UI port (default: 4747) |
-| `--no-proxy` | Web/console only, no ACP proxy |
-| `--session <id>` | Custom session ID |
-| `--setup` | Auto-detect and configure env vars |
-| `--debug` | Verbose logging |
----
 ## Storage
 Traces persist to `~/.copilot-tracer/traces.db` (SQLite). Safe to keep across sessions.
-To test the web UI without running a live Copilot session:
-```bash
-node test-seed.mjs   # seeds 4 sample traces (source build only)
-copilot-tracer --ui web --no-proxy --session test-session-001
-```
 ---
 ## Build & Publish
@@ -253,18 +224,24 @@ npx tsc          # compile to dist/
 To publish a new release to npm:
 ```bash
-# Bump patch version (1.0.0 → 1.0.1), build, publish, git-tag
+# Login first
+npm login
+# Patch version (1.0.4 → 1.0.5)
 bash scripts/publish.sh
-# Bump minor version
+# Minor version
 bash scripts/publish.sh minor
-# Publish a beta pre-release
+# Major version
+bash scripts/publish.sh major
+# Beta pre-release
 bash scripts/publish.sh --tag beta --pre beta
 ```
 The script will:
-1. Check npm authentication (`npm login` required first)
+1. Check npm authentication
 2. Verify git working tree is clean
 3. Type-check + build
 4. Verify `better-sqlite3` native module loads

package/dist/cli.js CHANGED Viewed

@@ -4,7 +4,8 @@ import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import readline from 'readline';
 import fs from 'fs';
-import { createSession, getTraces, getSessionSummary } from './db.js';
+import path from 'path';
+import { createSession, getTraces, getSessionSummary, ensureProject } from './db.js';
 import { handleAcpMessage, traceEvents } from './proxy.js';
 import { renderConsoleTable } from './consoleUi.js';
 import { startWebServer } from './webServer.js';
@@ -20,91 +21,109 @@ program
     .option('--session <id>', 'Filter by session ID')
     .option('--debug', 'Dump ALL raw ACP messages to stderr (use to discover real method names)')
     .option('--setup', 'Auto-detect copilot CLI + VS Code and configure OTLP env vars')
+    .option('--project-path <path>', 'Project source path (defaults to cwd)')
+    .option('--daemon', 'Run as background daemon — collects all OTLP data, no ACP proxy')
     .allowUnknownOption()
     .parse();
 const opts = program.opts();
 const port = parseInt(opts.port);
 // Handle --setup: patch env files, apply to current process, then fall through to start web UI
 if (opts.setup) {
-    runSetup(port);
-    // Force no-proxy web mode — user just needs to open the browser
-    opts.proxy = false;
-    opts.ui = 'web';
-}
-const sessionId = opts.session || randomUUID();
-createSession(sessionId);
-console.log(`\n  🤖 Copilot Tracer  |  Session: ${sessionId}\n`);
-// Start Web UI
-if (opts.ui === 'web' || opts.ui === 'both') {
-    startWebServer(port, sessionId);
-    setTimeout(() => open(`http://localhost:${port}/`), 1500);
+    runSetup(port, opts.daemon);
+    if (!opts.daemon) {
+        opts.proxy = false;
+        opts.ui = 'web';
+    }
 }
-// Start Console UI refresh loop
-if (opts.ui === 'console' || opts.ui === 'both') {
-    const refreshConsole = () => {
-        const entries = getTraces(sessionId, 50);
-        const summary = getSessionSummary(sessionId);
-        renderConsoleTable(entries, summary ?? undefined);
-    };
-    traceEvents.on('trace:update', refreshConsole);
-    traceEvents.on('trace:done', refreshConsole);
-    refreshConsole();
+// ── Daemon mode: run as always-on OTLP receiver ───────────────────────────
+if (opts.daemon) {
+    console.log(`\n  🤖 Copilot Tracer — Daemon Mode`);
+    console.log(`  📡 Listening for OTLP traces on port ${port}`);
+    console.log(`  🌐 Dashboard: http://localhost:${port}/`);
+    console.log(`  Press Ctrl+C to stop\n`);
+    startWebServer(port);
+    process.on('SIGINT', () => { process.exit(0); });
+    process.on('SIGTERM', () => { process.exit(0); });
 }
-// ACP Proxy — wrap copilot CLI
-if (opts.proxy !== false) {
-    const copilotArgs = ['--acp', '--stdio', ...program.args];
-    const child = spawn(opts.cmd, copilotArgs, {
-        stdio: ['pipe', 'pipe', 'inherit'],
-    });
-    if (!child.pid) {
-        console.error(`\n  ❌ Failed to start: ${opts.cmd} ${copilotArgs.join(' ')}`);
-        console.error('  Make sure GitHub Copilot CLI is installed: npm install -g @github/copilot-cli\n');
-        process.exit(1);
+else {
+    // ── Normal mode: per-session with optional ACP proxy ─────────────────────
+    const sessionId = opts.session || randomUUID();
+    // Resolve project path and create project record
+    const projectPath = opts.projectPath
+        ? path.resolve(opts.projectPath)
+        : process.cwd();
+    const projectId = ensureProject(projectPath);
+    createSession(sessionId, projectId);
+    console.log(`\n  🤖 Copilot Tracer  |  Session: ${sessionId}`);
+    console.log(`  📁 Project: ${projectPath}\n`);
+    // Start Web UI
+    if (opts.ui === 'web' || opts.ui === 'both') {
+        startWebServer(port, sessionId, projectId);
+        setTimeout(() => open(`http://localhost:${port}/`), 1500);
     }
-    // Parse newline-delimited JSON (NDJSON) from copilot
-    const stdinRl = readline.createInterface({ input: process.stdin });
-    const stdoutRl = readline.createInterface({ input: child.stdout });
-    const debug = opts.debug === true;
-    const logFile = debug ? fs.createWriteStream(`/tmp/copilot-tracer-${sessionId.slice(0, 8)}.ndjson`, { flags: 'a' }) : null;
-    function debugLog(direction, raw, parsed) {
-        if (!debug)
-            return;
-        const entry = JSON.stringify({ ts: new Date().toISOString(), dir: direction, raw, parsed });
-        process.stderr.write('[TRACER] ' + entry + '\n');
-        logFile?.write(entry + '\n');
+    // Start Console UI refresh loop
+    if (opts.ui === 'console' || opts.ui === 'both') {
+        const refreshConsole = () => {
+            const entries = getTraces(sessionId, 50);
+            const summary = getSessionSummary(sessionId);
+            renderConsoleTable(entries, summary ?? undefined);
+        };
+        traceEvents.on('trace:update', refreshConsole);
+        traceEvents.on('trace:done', refreshConsole);
+        refreshConsole();
     }
-    // stdin → copilot (user → copilot = 'out' direction from user's perspective)
-    stdinRl.on('line', (line) => {
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-            handleAcpMessage(sessionId, parsed, 'out'); // outbound = user sending to copilot
-        }
-        catch (e) {
-            // Not JSON — plain text from terminal, not ACP
-            if (debug)
-                process.stderr.write(`[TRACER] stdin non-JSON: ${line}\n`);
+    // ACP Proxy — wrap copilot CLI
+    if (opts.proxy !== false) {
+        const copilotArgs = ['--acp', '--stdio', ...program.args];
+        const child = spawn(opts.cmd, copilotArgs, {
+            stdio: ['pipe', 'pipe', 'inherit'],
+        });
+        if (!child.pid) {
+            console.error(`\n  ❌ Failed to start: ${opts.cmd} ${copilotArgs.join(' ')}`);
+            console.error('  Make sure GitHub Copilot CLI is installed: npm install -g @github/copilot-cli\n');
+            process.exit(1);
         }
-        debugLog('→ copilot', line, parsed);
-        child.stdin.write(line + '\n');
-    });
-    // copilot → stdout (copilot → user = 'in' direction from user's perspective)
-    stdoutRl.on('line', (line) => {
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-            handleAcpMessage(sessionId, parsed, 'in'); // inbound = copilot sending to user
+        const stdinRl = readline.createInterface({ input: process.stdin });
+        const stdoutRl = readline.createInterface({ input: child.stdout });
+        const debug = opts.debug === true;
+        const logFile = debug ? fs.createWriteStream(`/tmp/copilot-tracer-${sessionId.slice(0, 8)}.ndjson`, { flags: 'a' }) : null;
+        function debugLog(direction, raw, parsed) {
+            if (!debug)
+                return;
+            const entry = JSON.stringify({ ts: new Date().toISOString(), dir: direction, raw, parsed });
+            process.stderr.write('[TRACER] ' + entry + '\n');
+            logFile?.write(entry + '\n');
         }
-        catch (e) {
-            if (debug)
-                process.stderr.write(`[TRACER] stdout non-JSON: ${line}\n`);
-        }
-        debugLog('← copilot', line, parsed);
-        process.stdout.write(line + '\n');
-    });
-    child.on('exit', (code) => {
-        console.log(`\n  Copilot CLI exited (code ${code})\n`);
-        process.exit(code ?? 0);
-    });
-    process.on('SIGINT', () => { child.kill(); process.exit(0); });
+        stdinRl.on('line', (line) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+                handleAcpMessage(sessionId, parsed, 'out');
+            }
+            catch (e) {
+                if (debug)
+                    process.stderr.write(`[TRACER] stdin non-JSON: ${line}\n`);
+            }
+            debugLog('→ copilot', line, parsed);
+            child.stdin.write(line + '\n');
+        });
+        stdoutRl.on('line', (line) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+                handleAcpMessage(sessionId, parsed, 'in');
+            }
+            catch (e) {
+                if (debug)
+                    process.stderr.write(`[TRACER] stdout non-JSON: ${line}\n`);
+            }
+            debugLog('← copilot', line, parsed);
+            process.stdout.write(line + '\n');
+        });
+        child.on('exit', (code) => {
+            console.log(`\n  Copilot CLI exited (code ${code})\n`);
+            process.exit(code ?? 0);
+        });
+        process.on('SIGINT', () => { child.kill(); process.exit(0); });
+    }
 }