copilot-tracer 1.0.4 → 1.0.5

package/README.md

@@ -1,246 +1,196 @@
 # 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** 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 both Copilot CLI 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. 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 sessions automatically.
 
-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:
+---
+
+## How It Works
 
-```bash
-source ~/.zshrc
 ```
+┌─────────────────────────────────────────────────────────┐
+│  copilot-tracer --daemon (runs once, stays running)      │
+│                                                          │
+│  OTLP Receiver ← Copilot CLI + VS Code                   │
+│  (auto-detects project from github.copilot.git.repository)│
+│                                                          │
+│  SQLite DB → Dashboard + Live Tracer (Socket.io)         │
+└─────────────────────────────────────────────────────────┘
 
-Restart VS Code completely (Cmd+Q, then reopen).
+Copilot CLI / VS Code Copilot Chat
+         │
+         │  OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4747
+         ↓
+   POST /v1/traces (OpenTelemetry OTLP JSON)
+         │
+         ↓
+   copilot-tracer parses spans → 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
-```
-
-Open **http://localhost:4747** — shows "waiting for copilot CLI activity".
+# Web UI only (read from DB)
+copilot-tracer --ui web --no-proxy
 
----
+# 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
 
 ---
 
-## 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
 
 ---
 
-## 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
 ```
 
-Response shape:
+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 +203,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

@@ -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); });
+    }
 }