CCLens Trace Analyzer

cclens trace

enables Agents to complete trace location, Lead/Subagent selection, Markdown export, and subsequent analysis independently without relying on a browser UI. Users only need to provide vague clues, and the Agent will go through the complete workflow of

list → show → export → Read markdown

Pre-check

Before executing any trace commands, first confirm if

cclens trace

is available:

bash

cclens trace --help 2>&1

If the output starts with
```
Usage: cclens trace
```
→ Use
```
cclens trace
```
normally.
If the output shows Claude Code's help (
```
Usage: claude [options]
```
) → The currently installed
```
cclens
```
version does not include the trace feature. Upgrade to the latest version:

bash

npm install -g claude-code-lens

Run

cclens trace --help 2>&1

again after installation to confirm availability.

Core Principles

```
cclens trace
```
is the only trusted source. Do not open the browser UI or guess raw log paths.
Always use
```
-f json
```
. Treat CLI output as structured data, not natural language.
By default, select the narrowest scope that can answer the user's question — first check the
```
lead
```
or a single subagent, and export both for comparison if necessary.
```
--debug
```
is only used when troubleshooting attribution statistics, log file paths, or per-agent tool call distribution; do not add it for routine analysis.
When multiple sessions are matched, distinguish them using
```
startedAt
```
,
```
context
```
, and
```
status
```
before proceeding.

Workflow

1. List Candidate Sessions

bash

cclens trace list -f json

Parameter	Purpose
`--query <text>`	Match sessionId, context, status, agents, or agent names
`--since <iso-date>`	Only return sessions after the specified ISO 8601 timestamp
`--limit <n>`	Limit the number of returns (truncate before building summaries; non-positive integers will trigger `INVALID_ARGUMENT` )
`--max-preview <n>`	Truncate summary fields such as context, status, does, outcome (default 120–220 characters)

cclens trace list

returns an empty list, or the user's mentioned session cannot be found in the list, it means the session is a Claude Code session not started via cclens, and trace data cannot be obtained. In this case, directly inform the user: This session lacks trace records, possibly because it was not started using cclens. It is recommended to start Claude Code via cclens in the future to capture traces.

Key fields of each session:

```
sessionId
```
— Primary key for
```
show
```
and
```
export
```
```
startedAt
```
— Distinguish multiple runs of the same task
```
context
```
— The first model thinking or fallback session context, used to confirm the target trace
```
status
```
— Current or final result summary of the session
```
agents
```
— Overview of the number of agents, e.g.,
```
lead + 6 subagents
```

2. View Agents in the Session

bash

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

Key fields of each agent:

```
id
```
— Passed to
```
export --agent
```
```
role
```
—
```
lead
```
or
```
subagent
```
```
name
```
— Compact and recognizable name; subagent format is
```
<type> · <description>
```
```
does
```
— What the agent was assigned to do
```
outcome
```
— What the agent delivered

Select export targets based on user intent:

User Intent	Export Target	Matching Method
Troubleshoot overall process or task orchestration issues	`--agent lead`	Directly specify
Investigate the behavior or failure cause of a specific subagent	`--agent <id>`	Match by `name` ; check `does` if there is ambiguity
Compare collaboration between Lead and Subagent	Export `--agent lead` and `--agent <id>` separately	First use `lead` to view scheduling, then use the subagent id to view execution

Read the

context

and

status

in the

list

output before running

show

to avoid invalid operations on the wrong session.

3. Export Trace as Markdown

bash

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

Value	Scope
`lead`	Only the main Agent
`<id>`	Specified subagent (id comes from `show` output)

Specify output path:

bash

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

The

markdownPath

in the returned JSON is the absolute path to read in the next step. It also returns

agent.does

and

agent.outcome

. Confirm that the exported object matches the target before reading.

When

--out

is not specified, the default output path is

~/.claude-code-lens/exports/trace-<first 8 digits of session>-<agentId>.md

4. Read and Analyze Markdown

Use the

Read

tool to read

markdownPath

Key analysis points:

Overly broad, repetitive, or avoidable tool calls
Subagents where
```
does
```
does not match actual behavior
Excessively long thinking paths caused by unclear Skill instructions
Missing constraints, decision rules, or examples in Skills
Opportunities to reduce steps, tool calls, or agent handovers

Error Handling

All errors are returned as structured JSON. Read

error.code

to determine the recovery path; do not parse

message

for judgment.

Error Code	Trigger Condition	Recovery Method
`NO_LOGS`	No sessions captured in `raw_logs/`	Prompt the user to run CCLens to capture a session first
Empty list	`trace list` returns an empty array, or the user's mentioned session cannot be found	Inform the user: This session was not started via cclens, so trace data cannot be obtained. It is recommended to start Claude Code using cclens in the future
`SESSION_NOT_FOUND`	The specified `sessionId` does not exist in any logs	Re-run `trace list -f json` and select 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 select a valid `agents[].id`
`EXPORT_FAILED`	Markdown writing failed	Retry with `--out /tmp/<name>.md` , or report path/permission issues
`UNSUPPORTED_FORMAT`	Formats other than `json` / `yaml` / `yml` are used	Use `-f json` or `-f yaml`
`INVALID_ARGUMENT`	`--limit` or `--max-preview` is not a positive integer	Check parameter values and pass a valid positive integer

Reporting Requirements

Include the following elements in the report results; none can be missing:

Target session:
```
sessionId
```
and
```
startedAt
```
Target agent:
```
id
```
,
```
role
```
,
```
name
```
,
```
does
```
Evidence: Short quoted fragments from the exported Markdown; do not assert without basis
Recommendations: Specific modification plans for Skills or workflows, rather than general observations
Confidence: Indicate whether
```
--debug
```
was used, and whether the analysis covered the
```
lead
```
, a single subagent, or both

cclens-trace-analyzer

NPX Install

Tags

SKILL.md Content (Chinese)

CCLens Trace Analyzer

Pre-check

Core Principles

Workflow

1. List Candidate Sessions

2. View Agents in the Session

3. Export Trace as Markdown

4. Read and Analyze Markdown

Error Handling

Reporting Requirements