Run a CCGlass Debug Capture for Claude Code and Codex

When an AI coding agent makes a bad call, the visible chat transcript is often the wrong layer to debug. The model saw a system prompt, tool schemas, message history, provider routing, token cache state, and maybe a different base URL than the one you thought it was using. CCGlass is useful because it lets a developer inspect that traffic locally instead of guessing from the final answer.

The boundary matters. A local proxy that captures prompts and tool schemas is not a harmless UI widget. It produces logs that can contain source snippets, project paths, prompts, response bodies, usage data, and provider decisions. Use it like a debugging instrument for Claude Code or Codex, then handle the captured session as sensitive project data.

Use it when the transcript is too shallow

The ccglass README describes a local logging reverse proxy and dashboard for Claude Code, Codex, OpenCode, DeepSeek-TUI, Reasonix, Kimi, Ollama, OpenRouter, and related clients. That source detail is the reason this old article seed should survive. The tool is not just another wrapper around a chat window. It shows the full system prompt, tool schemas, message history, token and cache numbers, response timing, model filters, and request exports. In a Codex or Claude Code debugging session, that turns a vague complaint such as 'the agent chose the wrong tool' into a concrete inspection task: look at the menu of tools the model received, the call id it selected, the result that came back, and the next request that included that result.

The setup path is short, but the auth mode decides everything

The documented install path is npm install -g ccglass, followed by ccglass, ccglass claude, or ccglass codex. A focused capture can be as small as ccglass claude --resume for an existing Claude Code session or ccglass codex for a Codex API-key run. Under the hood, CCGlass points the client at a localhost base URL through the provider variable the client already reads. For Claude Code that can mean ANTHROPIC_BASE_URL; for Codex in API-key mode it means OPENAI_BASE_URL; for Bedrock it means ANTHROPIC_BEDROCK_BASE_URL. The sharp edge is Codex auth. The README says Codex traffic is captured only when Codex is in API-key mode. If codex doctor shows ChatGPT login mode, Codex uses a WebSocket path that bypasses OPENAI_BASE_URL, so the dashboard can stay empty even though the agent is working.

Run a small capture before changing prompts

A practical debugging run should be deliberately small. Step 1: run codex doctor if Codex is involved, because ChatGPT login mode will not pass through the OpenAI base URL. Step 2: run ccglass codex for Codex API-key mode or ccglass claude --resume for an existing Claude Code session. Step 3: reproduce one failing task, not a whole afternoon of work. Step 4: open the exact request where the agent went wrong, check the model name, inspect the tools list, and compare the response timing with the turn that followed. Step 5: if the evidence needs to leave the machine, use ccglass export <session>/<request> --format md for review notes or --format har for a network-level bug report. That gives the team a small artifact with a clear claim: this was the request, this was the tool menu, this was the model route, and this was the response.

Inspect routing before judging the agent

CCGlass is most valuable before you blame the model. Run one small failing task through ccglass claude --resume or ccglass codex, then inspect three things before editing prompts. First, check which provider and model actually handled the request. Second, compare the tools array with the tools you expected the agent to see. Third, export the suspect request as Markdown, JSON, raw HTTP, or HAR so the bug report is tied to a real request rather than a retelling. That workflow is a better fit for provider-routing bugs, missing tool schemas, bad cache assumptions, and context bloat than for broad judgments about whether one model is good or bad.

Provider support is a maintenance signal

The repository history makes CCGlass more interesting than a static proxy demo. Pull request 20 fixed Windows Codex routing around npm command shims and base-url normalization. Pull request 38 fixed Bedrock interception by using ANTHROPIC_BEDROCK_BASE_URL instead of the plain Anthropic variable and by making settings injection provider-specific. Pull request 50 added latency, theme, model filter, session stats, and timing views without changing capture semantics. Those are practical fixes from real agent setups. The editorial read is simple: this is worth a magazine article because it sits exactly where agent tooling breaks, at the boundary between CLI launch, provider endpoint, and request capture.

Do not turn the proxy into a trust boundary

A captured request proves what went over the local proxy. It does not prove the agent made a good plan, that a tool call was safe, or that a provider account should accept the same traffic in production. The README says new captures live under ~/.ccglass/sessions/, uses content-addressed blobs for long sessions, and masks auth tokens by default. That still leaves plenty of sensitive data: prompts, code fragments, filenames, tool schemas, errors, and model outputs. Keep --no-redact out of normal reviews, avoid sharing full HAR exports outside the project team, and delete or quarantine sessions after the debugging question is answered.

Proxy mode belongs to BYOK tools, not every IDE

ccglass proxy --provider openai and ccglass proxy --provider claude are useful when an IDE or client lets you set a custom API base URL. That makes the tool relevant beyond Claude Code and Codex, especially for BYOK setups in Cline, Continue, or similar clients. The same source page also draws the boundary: subscription-backed IDE models that route through a vendor backend cannot be inspected by simply pointing a base URL at localhost. Use proxy mode when you control the endpoint setting. Skip it when the client hides routing behind its own backend or uses a transport CCGlass does not intercept.

Where it fits in a serious agent workflow

Put CCGlass in the failure-analysis lane, not the daily happy path. It is a good fit when a Claude Code or Codex task repeatedly chooses the wrong tool, loses context between turns, sends a larger prompt than expected, misses cache behavior, or routes to the wrong provider. It is a poor fit as a permanent gateway for every request unless the team has decided where logs live, who may read them, how long sessions are kept, and what must be redacted before an export leaves the machine. If those answers are missing, run it for the one failure you need to inspect and then stop it.

Save CCGlass as an observability playbook for coding agents. It is strongest when it answers 'what did the agent actually send?' and weakest when teams treat capture as proof of correctness.

Practical takeaway

Run codex doctor first if you plan to inspect Codex. If it is in API-key mode, install with npm install -g ccglass, run ccglass codex or ccglass claude --resume, reproduce one failing task, inspect provider, model, tools, tokens, and latency, export only the request needed for review, and then remove or quarantine the session under ~/.ccglass/sessions/.