Technical Briefing: ccglass

The Problem

Coding agents (Claude Code, Codex, DeepSeek-TUI, etc.) send requests directly to API endpoints without respecting HTTP_PROXY/HTTPS_PROXY, making interception impossible with traditional proxies like mitmproxy. These agents are Node/native apps that establish HTTPS connections to upstream APIs themselves, meaning only the plain HTTP hop to localhost is visible. ccglass solves this by acting as a local reverse-proxy that the client connects to, capturing the full request flow without requiring CA certs or TLS pinning circumvention.

What This Does

ccglass is a local logging reverse-proxy with a web dashboard that captures everything a coding agent sends to its model. The codebase is organized around three primary domains: the proxy layer (src/proxy.js, src/forward-proxy.js), format handling for different providers (src/formats/openai.js, src/formats/anthropic.js, src/formats/index.js), and the web dashboard (web/app.js). The proxy intercepts the HTTP connection between the client and the real API, logging full request details including system prompts, tool schemas, message history, token/cache/cost metrics, and turn-to-turn diffs. The dashboard (web/app.js with 73 functions, calling into 3) renders this captured data in real time, with fmt, el, esc, and $ as the core rendering primitives defined there.

The internal call graph shows 535 resolved call edges between 54 JavaScript modules. Entry point main in src/cli.js:562 reaches 96 functions and is itself called from 1 place. The most connected modules are src/store (12 importers, 2 exports, instability 0.14) and src/cli (1 importer, 11 exports, instability 0.92). The store module is a hub: 12 other modules depend on it, and churn here has high-blast-radius. web/app.js is oversized at 1185 code lines, a change that ripples widely. Fourteen repeated 6-line code blocks appear across 11 files including src/classify.js, web/app.js, src/formats/openai.js, and src/parse.js — the recommendation is to extract shared helpers.

How It Is Wired

Execution begins at src/cli.js:562 (main), which reaches 96 functions and is the single caller of the CLI entry point. From main, control flows to wrap → settingsEnvBaseUrl, which reads the filesystem via fs.readFileSync to determine the provider and base URL. The proxy itself (src/proxy.js) sits between the client and the real API: the client establishes HTTPS to localhost, and ccglass makes the actual outbound network call (1 function makes an outbound network call, traced via apiExport → renderExport → toMarkdown → reassemble using openai.reassemble to a model). Key call edges include detectFormat called from 8 places, getAdapter from 8 places, and api from 8 places. The src/store.js module (27 functions, 1 class) is the central state hub called from 7 other files — it defines mask, pad, localSessionId, p, localTimestamp, and reads/writes files via blobRef, blobPath, writeBlob, readBlob, packRecord. The format modules each handle provider-specific parsing: src/formats/openai.js (13 functions, calls a model for inference, defines flatten, prettyArgs, toolView, isResponses, summary) and src/formats/anthropic.js (2 functions, 2 importers). The web dashboard (web/app.js) defines the rendering pipeline ($, el, esc, fmt, fmtMs) and handles session loading (loadSessions at line 110, reaching 59 functions), pick handling (onPick at line 272, reaching 50 functions), and live rendering (renderLive at line 1241, reaching 25 functions).

How To Use It

Setup: Install globally via npm install -g ccglass or via Homebrew: brew install jianshuo/tap/ccglass. The repository uses npm with a committed package-lock.json; in CI, npm ci should be used to respect the lockfile.

Configuration: No config file is required by default. Required environment variables depend on the provider — for Claude Code, ANTHROPIC_BASE_URL; for Codex, OPENAI_BASE_URL; for DeepSeek-based providers, DEEPSEEK_BASE_URL. API keys must be present in the client's environment (e.g., OPENAI_API_KEY for Codex in API-key mode).

Running it: Launch with ccglass to see the client selector, or name a provider directly: ccglass claude, ccglass codex, ccglass deepseek, ccglass reasonix, ccglass kimi, or ccglass opencode. Example: ccglass claude starts a proxy, points Claude Code at http://127.0.0.1:PORT via the ANTHROPIC_BASE_URL env var, launches Claude Code, and opens the dashboard at http://127.0.0.1:57633 (port varies per run).

Real-World Use

A team wants to audit what their Claude Code instance is sending to Anthropic — message history, tool schemas, token usage, and cost. They run ccglass claude, which configures the proxy, starts Claude Code pointing at the local endpoint, and opens the dashboard. Every request appears in real time: the full system prompt, each tool call's schema and parameters, the message history array, and per-request token/cache/cost numbers. The turn-to-turn diff view shows exactly what changed between turns. The team identifies that Claude Code is sending an unexpectedly large system prompt and a tool that the agent never actually uses, prompting a prompt engineering revision.

Code Health & Issues

The static analysis identified 20 findings across 5 categories:

  • [CRITICAL] Keep secrets out of workflows a fork can trigger — .github/workflows/claude.yml contains CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_TRIGGER_PAT (publish or cloud scope). Contributor-controlled input reaches a job holding a publish token or cloud credential, so a pull request becomes credential exfiltration. Fix: move secret-using steps into a workflow_run job that never checks out pull request code, or gate on an environment with required reviewers.
  • [HIGH] Pin third-party GitHub Actions to a commit SHA — .github/workflows uses anthropics/claude-code-action@v1. A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed. Fix: replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.
  • [MEDIUM] Enable Dependabot or Renovate — 1 manifest(s), no update bot configured. Without a bot a published advisory sits unpatched until someone audits by hand. Fix: commit .github/dependabot.yml covering the repo ecosystems plus github-actions.
  • [MEDIUM] Install from the lockfile in CI — .github/workflows uses npm install with a committed package-lock.json. A fresh resolution in CI means the tested dependency set is not the locked one. Fix: use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.
  • [MEDIUM] Gate pull requests on a dependency vulnerability scan — no dependency scan in CI. This is the one gate that would catch a known-vulnerable package before it reaches a build. Fix: add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Beyond these measured findings: the repository has proper CI (GitHub Actions), tests (25 files), a license, and a lockfile. No committed secrets outside workflows. The web/app.js oversize and duplicated code blocks are the most significant maintainability risks for ongoing development.

The Bottom Line

ccglass is a focused, practical tool that solves a genuine interception problem for coding agents that ignore standard proxies. The code is well-structured for its domain (proxy + format handling + dashboard), with measurable maintainability issues — primarily the oversized web/app.js, duplicated logic across format modules, and the store hub having high blast radius. The CRITICAL credential exposure in workflows must be addressed before the project is shared beyond a trusted inner circle. It's well-suited for teams needing to audit or debug coding agent behavior; the credential hygiene fix is the highest-priority item before wider distribution.