cclens-trace-analyzer

CCLens Trace Analyzer

cclens trace Let the Agent complete trace location, Lead/Subagent selection, Markdown export, and subsequent analysis on its own without relying on the browser UI. The user only needs to provide vague clues, and the Agent goes through the list → show → export → Read markdown complete workflow.

Prerequisite Check

Before executing any trace command, first confirm whether cclens trace is available:

cclens trace --help 2>&1

• If the output starts with Usage: cclens trace → use normally cclens trace。
• If the output is Claude Code's help (Usage: claude [options]) → it means the currently installed cclens version does not yet include the trace feature; upgrade to the latest version:

npm install -g claude-code-lens

After installation is complete, run cclens trace --help 2>&1 again to confirm it is available.

Core Principles

• cclens trace is the only trustworthy source. Do not open the browser UI, and do not guess the raw log path.
• Always use -f json. Treat CLI output as structured data, not natural language.
• By default, choose the narrowest scope that can answer the user's question — first look at lead or a single subagent, and if necessary export both separately for comparison.
• --debug Use only when you need to troubleshoot attribution statistics, log file paths, or per-agent tool call distribution; do not add it for routine analysis.
• When multiple sessions match, use startedAt、context and status to distinguish them before continuing.

Workflow

1. List Candidate Sessions

cclens trace list -f json

Parameter	Purpose
--query <text>	Match sessionId, context, status, agents, or agent name
--since <iso-date>	Return only sessions after the specified ISO 8601 timestamp
--limit <n>	Limit the number returned (truncated before building the summary; a non-positive integer will trigger INVALID_ARGUMENT）
--max-preview <n>	Truncate summary fields such as context, status, does, outcome (default varies from 120–220 characters)

If cclens trace list returns an empty list, or the session mentioned by the user cannot be found in the list, it means that session was not a Claude Code launched through cclens, and trace data cannot be obtained. In this case, directly tell the user: that session lacks trace records, possibly because it was not launched using cclens; suggest launching Claude Code through cclens in the future so that traces can be captured.

Key fields for each session:

• sessionId — show and export primary key
• startedAt — distinguish multiple runs of the same task
• context — the first model thinking or fallback session context, used to confirm the target trace
• status — summary of the session's current or final result
• agents — overview of the number of agents, such as lead + 6 subagents

2. View Agents in the Session

cclens trace show --session <sessionId> -f json

Key fields for each agent:

• id — passed to export --agent
• role — lead or subagent
• name — compact recognizable name; subagent format is <type> · <description>
• does — what this agent was dispatched to do
• outcome — what this agent delivered

Choose the export target according to user intent:

User Intent	Export Target	Matching Method
Troubleshoot the overall process and task orchestration issues	--agent lead	Specify directly
Investigate the behavior or failure cause of a certain subagent	--agent <id>	Match by name ; when ambiguous, look at does
Compare the collaboration between Lead and Subagent	Export separately --agent lead and --agent <id>	First use lead to view the scheduling, then use the subagent id to view execution

Before running show , first read list in the output of context and status, to avoid performing invalid operations on the wrong session.

3. Export Trace as Markdown

cclens trace export --session <sessionId> --agent <agentId|lead> -f json

Value	Scope
lead	Main Agent only
<id>	Specified subagent (id comes from show output)

Specify output path:

cclens trace export --session <sessionId> --agent <id> --out /tmp/cclens-<session>-<agent>.md -f json

In the returned JSON, markdownPath is the absolute path to read next; it also returns agent.does and agent.outcome; before reading, first confirm that the export target matches the goal.

When --out is not specified, the default output goes to ~/.claude-code-lens/exports/trace-<session前8位>-<agentId>.md。

4. Read and analyze Markdown

For markdownPath , read using the Read tool.

Analysis focus:

• Tool calls with too large a scope, duplicates, or that are avoidable
• does Subagents inconsistent with actual behavior
• Overly long thinking paths caused by unclear Skill instructions
• Missing constraints, decision rules, or examples in the Skill
• Opportunities to reduce steps, tool calls, or agent handoffs

Error handling

All errors are returned as structured JSON. Read error.code to determine the recovery path; do not parse message to make judgments.

Error code	Trigger condition	Recovery method
NO_LOGS	raw_logs/ No session captured in	Prompt the user to run CCLens first to capture a session
List is empty	trace list returns an empty array, or the session mentioned by the user cannot be found	Inform the user: this session was not started through cclens, so the trace cannot be obtained. Suggest using cclens to start Claude Code in the future
SESSION_NOT_FOUND	The specified sessionId does not exist in any log	Re-run trace list -f json, and choose a valid sessionId
AGENT_NOT_FOUND	The specified agent id does not exist in the session	Re-run trace show --session <id> -f json, and choose a valid agents[].id
EXPORT_FAILED	Markdown write failed	Use --out /tmp/<name>.md to retry, or report the path/permission issue
UNSUPPORTED_FORMAT	Used json/yaml/yml a format other than	Use -f json or -f yaml
INVALID_ARGUMENT	--limit or --max-preview is not a positive integer	Check the parameter value and pass a valid positive integer

Reporting requirements

When reporting results, include the following elements; none may be omitted:

• Target session：sessionId and startedAt
• Target agent：id、role、name、does
• Evidence: brief quoted snippets from the exported Markdown, without making unfounded assertions
• Recommendations: concrete Skill or workflow modification plans, rather than general observations
• Confidence: state whether --debugwas used, and analyzed lead, a single subagent, or both analyzed it