Claude Code Lens

Claude Code Lens is a local observability tool for Claude Code. It runs an Anthropic-compatible proxy between Claude Code and the real upstream service, records system prompts, messages, tool definitions, tool calls, streaming responses, and token usage, then lets you inspect them in a browser.

It is designed for two workflows:

• One-off debugging: launch a monitored Claude Code session without changing your Claude Code settings. Running cclens opens Claude Code in interactive mode while also starting the proxy and visualizer; append any Claude Code arguments when you need another mode, such as cclens -p "..." or cclens --resume, and they are passed through automatically.
• Long-running monitoring: keep a local proxy running and explicitly point Claude Code at it for ongoing log capture. Use cclens proxy, then start Claude Code with the generated settings file or an environment variable.

Why use it:

• Zero-config by default: it can discover the real base URL used by your existing Claude Code setup.
• Non-invasive: it does not patch Claude Code; one-shot mode does not write to ~/.claude/settings.json or project .claude/settings.json.
• Full request visibility: inspect system prompts, message history, tool schemas, tool calls, streaming output, and token usage.
• Useful for tool/MCP debugging: verify the exact tool definitions and prompts Claude Code sent to the model.
• Local-first: runtime config and logs live in ~/.claude-code-lens/.

Preview

The visualizer splits each Claude Code request into input context, model output, and resources. You can inspect system prompts, messages, tool definitions, token usage, and collapse long message history when reviewing larger sessions.

Install

Install the cclens CLI:

npm install -g claude-code-lens

From a local checkout:

npm install
npm install -g .

The npm package name is claude-code-lens, and the installed command is cclens.

Optional: install the Claude Code Skill for agent-driven trace analysis:

npx skills add ningzimu/claude-code-lens --skill cclens-trace-analyzer

For a global, non-interactive install:

npx skills add ningzimu/claude-code-lens --skill cclens-trace-analyzer -g -y

The Skill install only adds the Agent Skill. It does not run npm install -g claude-code-lens, so install the CLI first if you want the agent to use cclens trace.

Usage

Use one CLI prefix for both monitor commands and Claude Code passthrough. There are two recommended modes.

Mode 1: Launch Claude Code With Monitoring

This is the simplest mode for temporary prompt, tool, MCP, or token usage debugging. Running cclens starts an interactive Claude Code session and turns monitoring on automatically.

cclens
cclens -p "hello"
cclens --resume

One-shot mode:

1. Starts the local proxy, default http://localhost:18888.
2. Starts the log visualizer, default http://127.0.0.1:5500.
3. Opens the browser.
4. Launches Claude Code in interactive mode; if you pass Claude Code arguments after cclens, they are forwarded unchanged.

Except for monitor subcommands (proxy, stop, status, viz, extract, config, help), every argument is passed through to Claude Code automatically. Any Claude Code flag can be appended directly to cclens.

This mode does not modify your Claude Code user or project settings. It only injects the proxy environment into the launched Claude Code process and uses ~/.claude-code-lens/settings.json as a generated settings file. To stop the background proxy, run:

cclens stop

Mode 2: Long-Running Proxy Monitoring

If you want Claude Code to keep using the same local proxy over time, start the proxy manually.

cclens proxy

The command generates:

~/.claude-code-lens/settings.json

Start Claude Code with that settings file:

claude --settings ~/.claude-code-lens/settings.json

Or configure only the current shell session:

ANTHROPIC_BASE_URL=http://localhost:18888 claude

Open the monitor UI:

cclens viz

Default URL:

http://127.0.0.1:5500

Long-running mode is better for continuous monitoring. One-shot mode is better for temporary, no-config debugging.

Stop the proxy:

cclens stop

Check status:

cclens status

CLI Help

Every monitor subcommand has dedicated help:

cclens --help
cclens --version
cclens proxy --help
cclens help proxy

Command reference:

Agent-Driven Trace Analysis

A Claude Code Skill is included at skills/cclens-trace-analyzer/. Install it with:

npx skills add ningzimu/claude-code-lens --skill cclens-trace-analyzer

When loaded into Claude Code, the agent can run cclens trace list → show → export → Read on its own — no browser UI needed. It locates sessions by ID fragment or time clues, inspects Lead/Subagent behavior, exports Markdown, and reports findings with evidence and recommendations.

Visualizer

The visualizer opens automatically during one-click startup. Set CLAUDE_CODE_LENS_OPEN_BROWSER=false to disable that behavior.
Startup output is intentionally brief. Set CLAUDE_CODE_LENS_VERBOSE=true to print process IDs, log paths, and startup steps.

User Directory

Runtime data is stored outside the repository:

~/.claude-code-lens/
  config.json       # user config
  settings.json     # generated Claude Code settings file
  logs/             # proxy and visualizer process logs
  raw_logs/         # captured API interactions
  prompts/          # extracted prompts and tools

config.json is optional. By default, cclens discovers the target Anthropic-compatible base URL from your existing Claude Code environment and settings.

Target discovery priority:

CLAUDE_CODE_LENS_TARGET_BASE_URL
> ~/.claude-code-lens/config.json target.baseUrl
> ANTHROPIC_BASE_URL from the current shell
> Claude Code settings env.ANTHROPIC_BASE_URL
  - custom --settings file
  - .claude/settings.local.json
  - .claude/settings.json
  - ~/.claude/settings.json
> https://api.anthropic.com

Example ~/.claude-code-lens/config.json for manual overrides:

{
  "proxy": {
    "host": "0.0.0.0",
    "port": 18888
  },
  "target": {
    "baseUrl": "https://api.anthropic.com",
    "timeout": 120000
  },
  "visualizer": {
    "host": "127.0.0.1",
    "port": 5500
  }
}

General configuration priority:

environment variables
> ~/.claude-code-lens/config.json
> Claude Code settings discovery
> built-in defaults

Supported environment overrides:

CLAUDE_CODE_LENS_HOME=~/.claude-code-lens
CLAUDE_CODE_LENS_PROXY_HOST=127.0.0.1
CLAUDE_CODE_LENS_PROXY_PORT=18888
CLAUDE_CODE_LENS_TARGET_BASE_URL=https://api.anthropic.com
CLAUDE_CODE_LENS_TARGET_TIMEOUT=120000
CLAUDE_CODE_LENS_VISUALIZER_PORT=5500
CLAUDE_CODE_LENS_LOGGING_ENABLE_CONSOLE=true
CLAUDE_CODE_LENS_OPEN_BROWSER=false
CLAUDE_CODE_LENS_VERBOSE=true

Logs

API interaction logs:

ls ~/.claude-code-lens/raw_logs/

Proxy server logs:

tail -f ~/.claude-code-lens/logs/proxy-server.log

Sensitive request headers such as authorization and x-api-key are masked in logs. Request and response bodies can still contain private project context, so review logs before sharing them.

Project Layout

bin/                  # unified cclens CLI
src/cli/              # command orchestration
src/proxy/            # local proxy and session logger
src/visualizer/       # browser UI for reading raw_logs
src/extractor/        # prompt/tool extraction implementation
skills/               # Claude Code Skills (trace analyzer)
tests/                # CLI and proxy behavior tests

Development

npm install
npm test
npm run check

Package contents can be checked with:

npm pack --dry-run