context-lens 0.1.0

package/.idea/context-lens.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="jdk" jdkName="Python 3.9" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="PLAIN" />
+    <option name="myDocStringFormat" value="Plain" />
+  </component>
+</module>

package/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,17 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="HtmlUnknownAttribute" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="myValues">
+        <value>
+          <list size="1">
+            <item index="0" class="java.lang.String" itemvalue="className" />
+          </list>
+        </value>
+      </option>
+      <option name="myCustomValuesEnabled" value="true" />
+    </inspection_tool>
+    <inspection_tool class="JSHint" enabled="true" level="ERROR" enabled_by_default="true" />
+  </profile>
+</component>

package/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

package/.idea/material_theme_project_new.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MaterialThemeProjectNewConfig">
+    <option name="metadata">
+      <MTProjectMetadataState>
+        <option name="userId" value="-6abbd721:19c326b38fc:-66b2" />
+      </MTProjectMetadataState>
+    </option>
+  </component>
+</project>

package/.idea/misc.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.9" />
+  </component>
+  <component name="KubernetesApiPersistence">{}</component>
+  <component name="KubernetesApiProvider"><![CDATA[{
+  "isMigrated": true
+}]]></component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.9" project-jdk-type="Python SDK" />
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/context-lens.iml" filepath="$PROJECT_DIR$/.idea/context-lens.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## [0.2.0] - 2026-02-07
+
+### Added - CLI Wrapper with Multi-Client Support
+
+#### Major Features
+- **CLI Wrapper** (`cli.js`) - Launch any tool through Context Lens with automatic setup
+  - Usage: `npx context-lens <tool> [args...]`
+  - Automatically starts proxy and web UI
+  - Sets environment variables for the tool
+  - Opens browser at http://localhost:4041
+  - Full TTY/interactivity support
+
+- **Multi-Client Support** - Run multiple tools simultaneously sharing one proxy
+  - First client starts the proxy
+  - Subsequent clients detect and attach to existing proxy
+  - Reference counting via `/tmp/context-lens.lock`
+  - Only last client to exit shuts down the proxy
+  - Each client shows attachment status and active client count
+
+- **Source Tagging** - Identify which tool made each request
+  - Tool name encoded in base URL path: `http://localhost:4040/<tool-name>`
+  - Proxy extracts source and stores with each request
+  - Web UI displays source badge for each request
+  - Example: `[anthropic] [claude] claude-sonnet-4`
+
+#### Technical Changes
+- `cli.js` (new):
+  - Port detection via TCP connect
+  - Reference counting with atomic file operations
+  - Smart shutdown logic
+  - Signal handling (SIGINT/SIGTERM)
+  - Tool-specific environment variable mapping
+
+- `server.js`:
+  - Added `extractSource()` function for URL path parsing
+  - Updated `storeRequest()` to accept source parameter
+  - Modified `handleProxy()` to extract and pass source
+  - Enhanced web UI to display source badges
+  - Added CSS styling for source tags
+
+- `package.json`:
+  - Added `bin` field for `npx` support
+
+#### Documentation
+- **README.md** - Updated with CLI-first usage examples
+- **CLI-IMPLEMENTATION.md** - Technical implementation details
+- **MULTI-CLIENT.md** - Comprehensive multi-client guide
+- **CHANGELOG.md** - This file
+
+#### Testing
+- ✅ Single client mode
+- ✅ Multi-client attach/detach
+- ✅ Reference counting accuracy
+- ✅ Source tag extraction and display
+- ✅ Graceful shutdown
+- ✅ Lockfile cleanup
+- ✅ Port conflict handling
+
+#### Known Limitations
+- Lockfile at `/tmp/` may not work on all systems (e.g., Windows without WSL)
+- No IPC - relies on filesystem for coordination
+- Manual cleanup needed if clients crash without cleanup
+- Browser auto-open uses platform detection (may fail on exotic systems)
+
+#### Example Usage
+
+**Single Tool:**
+```bash
+npx context-lens claude "Explain quantum computing"
+# Starts proxy, opens UI, runs claude
+```
+
+**Multiple Tools (different terminals):**
+```bash
+# Terminal 1
+npx context-lens claude "task 1"
+# → Starts proxy
+
+# Terminal 2 (while T1 running)
+npx context-lens codex "task 2"
+# → Attaches to proxy
+
+# Terminal 3 (while T1+T2 running)
+npx context-lens -- python agent.py
+# → Also attaches
+
+# All requests visible in shared UI with source tags
+```
+
+---
+
+## [0.1.0] - 2026-02-07
+
+### Initial Release
+- HTTP proxy server (port 4040)
+- Web UI dashboard (port 4041)
+- Request capture and analysis
+- Token estimation (char/4 heuristic)
+- Provider detection (Anthropic/OpenAI)
+- Context usage visualization
+- Streaming response support
+- Zero external dependencies

package/README.md

@@ -0,0 +1,60 @@
+# Context Lens
+
+See what's actually in your LLM's context window. A zero-dependency HTTP proxy that intercepts API calls and visualizes token usage in real-time.
+
+> **Early Development** — Expect rough edges. Contributions welcome.
+
+## Quick Start
+
+```bash
+npx context-lens claude "your prompt"
+npx context-lens codex "your prompt"
+npx context-lens aider --model claude-sonnet-4
+npx context-lens -- python my_agent.py
+```
+
+This starts the proxy (port 4040), opens the web UI (http://localhost:4041), sets the right env vars, and runs your command. Multiple tools can share one proxy — just open more terminals.
+
+## What You Get
+
+- **Token breakdown** — system prompts, tools, messages with visual context bar
+- **Conversation threading** — groups API calls by session/conversation, shows agents and turns
+- **Content formatting** — collapsible system prompts, typed message blocks (text/tool_use/tool_result), per-tool schemas
+- **Auto-detection** — recognizes Claude Code, Codex, aider, and others by source tag or system prompt
+- **Streaming support** — passes through SSE chunks in real-time
+
+## Manual Mode
+
+```bash
+node server.js
+# Port 4040 = proxy, port 4041 = web UI
+
+ANTHROPIC_BASE_URL=http://localhost:4040 claude "your prompt"
+OPENAI_BASE_URL=http://localhost:4040 codex "your prompt"
+```
+
+### Source Tagging
+
+Add a path prefix to tag requests by tool:
+
+```bash
+ANTHROPIC_BASE_URL=http://localhost:4040/claude claude "prompt"
+OPENAI_BASE_URL=http://localhost:4040/aider aider "prompt"
+```
+
+### Codex Subscription Mode
+
+Codex with a ChatGPT subscription needs mitmproxy for HTTPS interception (Cloudflare blocks reverse proxies). The CLI handles this automatically — just make sure `mitmdump` is installed:
+
+```bash
+pipx install mitmproxy
+npx context-lens codex "your prompt"
+```
+
+## Data
+
+All captured requests are logged to `data/requests.jsonl` and kept in memory (last 100). Restart clears the in-memory state; the JSONL log persists.
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const { join } = require('path');
+const { platform } = require('os');
+const fs = require('fs');
+const net = require('net');
+
+// Known tool config: env vars for the child process, extra CLI args, server env vars, and whether mitmproxy is needed
+const PROXY_URL = 'http://localhost:4040';
+const MITM_PORT = 8080;
+const MITM_PROXY_URL = `http://localhost:${MITM_PORT}`;
+
+const TOOL_CONFIG = {
+  'claude': {
+    childEnv: { ANTHROPIC_BASE_URL: PROXY_URL },
+    extraArgs: [],
+    serverEnv: {},
+    needsMitm: false,
+  },
+  'codex': {
+    // Codex subscription uses chatgpt.com with Cloudflare — needs forward proxy (mitmproxy)
+    // to intercept HTTPS traffic without breaking TLS fingerprinting.
+    childEnv: {
+      https_proxy: MITM_PROXY_URL,
+      SSL_CERT_FILE: join(process.env.HOME || '', '.mitmproxy', 'mitmproxy-ca-cert.pem'),
+    },
+    extraArgs: [],
+    serverEnv: {},
+    needsMitm: true,
+  },
+  'aider': {
+    childEnv: { ANTHROPIC_BASE_URL: PROXY_URL, OPENAI_BASE_URL: PROXY_URL },
+    extraArgs: [],
+    serverEnv: {},
+    needsMitm: false,
+  },
+};
+
+function getToolConfig(toolName) {
+  return TOOL_CONFIG[toolName] || {
+    childEnv: { ANTHROPIC_BASE_URL: PROXY_URL, OPENAI_BASE_URL: PROXY_URL },
+    extraArgs: [],
+    serverEnv: {},
+    needsMitm: false,
+  };
+}
+
+const LOCKFILE = '/tmp/context-lens.lock';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  // Standalone mode: just start the proxy server
+  const serverPath = join(__dirname, 'server.js');
+  const server = spawn('node', [serverPath], { stdio: 'inherit' });
+  server.on('exit', (code) => process.exit(code || 0));
+  process.on('SIGINT', () => server.kill('SIGINT'));
+  process.on('SIGTERM', () => server.kill('SIGTERM'));
+  // Prevent early exit
+  process.stdin.resume();
+  return;
+}
+
+// Skip '--' separator if present
+let commandArgs = args;
+if (args[0] === '--') {
+  commandArgs = args.slice(1);
+}
+
+if (commandArgs.length === 0) {
+  console.error('Error: No command specified after --');
+  process.exit(1);
+}
+
+const commandName = commandArgs[0];
+const commandArguments = commandArgs.slice(1);
+
+// Get tool-specific config
+const toolConfig = getToolConfig(commandName);
+
+// Check if proxy is already running
+function isProxyRunning() {
+  return new Promise((resolve) => {
+    const socket = net.connect({ port: 4040, host: 'localhost' }, () => {
+      socket.end();
+      resolve(true);
+    });
+    socket.on('error', () => resolve(false));
+    socket.setTimeout(1000, () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
+// Increment reference count in lockfile
+function incrementRefCount() {
+  try {
+    let count = 0;
+    if (fs.existsSync(LOCKFILE)) {
+      const data = fs.readFileSync(LOCKFILE, 'utf8');
+      count = parseInt(data) || 0;
+    }
+    fs.writeFileSync(LOCKFILE, String(count + 1));
+    return count + 1;
+  } catch (err) {
+    console.error('Warning: failed to update lockfile:', err.message);
+    return 1;
+  }
+}
+
+// If the proxy isn't actually running but a lockfile exists, it's stale (e.g. prior crash).
+function clearStaleLockfile() {
+  try {
+    if (fs.existsSync(LOCKFILE)) fs.unlinkSync(LOCKFILE);
+  } catch (err) {
+    console.error('Warning: failed to clear stale lockfile:', err.message);
+  }
+}
+
+// Decrement reference count in lockfile
+function decrementRefCount() {
+  try {
+    if (!fs.existsSync(LOCKFILE)) return 0;
+    const data = fs.readFileSync(LOCKFILE, 'utf8');
+    const count = Math.max(0, (parseInt(data) || 1) - 1);
+    if (count === 0) {
+      fs.unlinkSync(LOCKFILE);
+    } else {
+      fs.writeFileSync(LOCKFILE, String(count));
+    }
+    return count;
+  } catch (err) {
+    console.error('Warning: failed to update lockfile:', err.message);
+    return 0;
+  }
+}
+
+let serverProcess = null;
+let mitmProcess = null;
+let serverReady = false;
+let mitmReady = false;
+let childProcess = null;
+let shouldShutdownProxy = false;
+
+// Start proxy or attach to existing one
+async function initializeProxy() {
+  const alreadyRunning = await isProxyRunning();
+  
+  if (alreadyRunning) {
+    console.log('🔍 Context Lens proxy already running, attaching to it...');
+    incrementRefCount();
+    serverReady = true;
+    shouldShutdownProxy = false;
+    maybeStartMitmThenChild();
+  } else {
+    console.log('🔍 Starting Context Lens proxy and web UI...');
+    // No proxy is listening on :4040. Any existing lockfile is stale and would prevent shutdown later.
+    clearStaleLockfile();
+    incrementRefCount();
+    shouldShutdownProxy = true;
+    
+    const serverPath = join(__dirname, 'server.js');
+    serverProcess = spawn('node', [serverPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: false,
+      env: { ...toolConfig.serverEnv, ...process.env, CONTEXT_LENS_CLI: '1' },
+    });
+
+    // Wait for server to be ready, then suppress output (visible in web UI at :4041)
+    serverProcess.stdout.on('data', (data) => {
+      const output = data.toString();
+      if (!serverReady) {
+        process.stderr.write(output);
+      }
+      if (output.includes('Context Lens Web UI running') && !serverReady) {
+        serverReady = true;
+        maybeStartMitmThenChild();
+      }
+    });
+
+    serverProcess.stderr.on('data', (data) => {
+      if (!serverReady) {
+        process.stderr.write(data);
+      }
+    });
+
+    serverProcess.on('error', (err) => {
+      console.error('Failed to start server:', err);
+      decrementRefCount();
+      process.exit(1);
+    });
+
+    serverProcess.on('exit', (code) => {
+      if (!serverReady) {
+        console.error('Server exited unexpectedly');
+        decrementRefCount();
+        process.exit(code || 1);
+      }
+    });
+
+    // Open browser after a short delay (only when starting new server)
+    setTimeout(() => {
+      openBrowser('http://localhost:4041');
+    }, 1000);
+  }
+}
+
+initializeProxy();
+
+// Start mitmproxy if needed, then start the child
+function maybeStartMitmThenChild() {
+  if (!toolConfig.needsMitm) {
+    return startChild();
+  }
+
+  const addonPath = join(__dirname, 'mitm_addon.py');
+  console.log('🔒 Starting mitmproxy (forward proxy for HTTPS interception)...');
+
+  mitmProcess = spawn('mitmdump', ['-s', addonPath, '--quiet', '--listen-port', String(MITM_PORT)], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  mitmProcess.on('error', (err) => {
+    console.error('Failed to start mitmproxy:', err.message);
+    console.error('Install it: pipx install mitmproxy');
+    cleanup(1);
+  });
+
+  mitmProcess.on('exit', (code) => {
+    if (!mitmReady) {
+      console.error('mitmproxy exited unexpectedly');
+      cleanup(code || 1);
+    }
+  });
+
+  // Poll until mitmproxy is accepting connections
+  const pollMitm = setInterval(() => {
+    const socket = net.connect({ port: MITM_PORT, host: 'localhost' }, () => {
+      socket.end();
+      if (!mitmReady) {
+        mitmReady = true;
+        clearInterval(pollMitm);
+        console.log(`🔒 mitmproxy listening on port ${MITM_PORT}`);
+        startChild();
+      }
+    });
+    socket.on('error', () => {}); // not ready yet
+    socket.setTimeout(500, () => socket.destroy());
+  }, 200);
+}
+
+// Start the child command
+function startChild() {
+  // Inject extra args (e.g. codex -c chatgpt_base_url=...) before user args
+  const allArgs = [...toolConfig.extraArgs, ...commandArguments];
+  console.log(`\n🚀 Launching: ${commandName} ${allArgs.join(' ')}\n`);
+
+  const childEnv = {
+    ...process.env,
+    ...toolConfig.childEnv,
+  };
+
+  // Spawn the child process with inherited stdio (interactive)
+  // No shell: true — avoids intermediate process that breaks signal delivery
+  childProcess = spawn(commandName, allArgs, {
+    stdio: 'inherit',
+    env: childEnv,
+  });
+
+  childProcess.on('error', (err) => {
+    console.error(`\nFailed to start ${commandName}:`, err.message);
+    cleanup(1);
+  });
+
+  // When the child exits (however it happens), clean up and mirror its exit code
+  childProcess.on('exit', (code, signal) => {
+    cleanup(signal ? 128 + (signal === 'SIGINT' ? 2 : 15) : (code || 0));
+  });
+}
+
+// Open browser (cross-platform)
+function openBrowser(url) {
+  const cmd = platform() === 'darwin' ? 'open' 
+    : platform() === 'win32' ? 'start' 
+    : 'xdg-open';
+  
+  const browserProcess = spawn(cmd, [url], {
+    stdio: 'ignore',
+    detached: true,
+  });
+  
+  browserProcess.unref(); // Don't wait for browser to close
+}
+
+// Cleanup on exit
+function cleanup(exitCode) {
+  if (cleanup._didRun) return;
+  cleanup._didRun = true;
+
+  const remainingRefs = decrementRefCount();
+
+  if (mitmProcess && !mitmProcess.killed) {
+    mitmProcess.kill();
+  }
+
+  if (remainingRefs === 0 && shouldShutdownProxy && serverProcess && !serverProcess.killed) {
+    serverProcess.kill();
+  }
+
+  process.exit(exitCode);
+}
+
+// Ignore SIGINT in the parent — let it flow to the child (claude/codex) naturally.
+// The child handles Ctrl+C itself; when it eventually exits, cleanup runs via the 'exit' handler.
+process.on('SIGINT', () => {});
+
+// SIGTERM: external shutdown request — forward to child
+process.on('SIGTERM', () => {
+  if (childProcess && !childProcess.killed) childProcess.kill('SIGTERM');
+});

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "context-lens",
+  "version": "0.1.0",
+  "description": "Local HTTP proxy that intercepts LLM API calls and visualizes context windows",
+  "main": "server.js",
+  "bin": {
+    "context-lens": "./cli.js"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "keywords": ["llm", "proxy", "context", "anthropic", "openai", "visualization"],
+  "author": "Lars de Ridder",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/larsderidder/context-lens"
+  },
+  "license": "MIT"
+}