Back to Details

cclens-trace-analyzer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CCLens Trace Analyzer

CCLens Trace Analyzer

cclens trace
让 Agent 不依赖浏览器 UI，自己完成 trace 定位、Lead/Subagent 选择、Markdown 导出和后续分析。用户只需提供模糊线索，Agent 走完 
list → show → export → Read markdown
的完整流程。
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

执行任何 trace 命令前，先确认 
cclens trace
是否可用：
bash
cclens trace --help 2>&1
  • 如果输出以 
    Usage: cclens trace
    开头 → 正常使用 
    cclens trace
    。
  • 如果输出的是 Claude Code 的帮助（
    Usage: claude [options]
    ）→ 说明当前安装的 
    cclens
    版本还不包含 trace 功能，升级到最新版本：
bash
npm install -g claude-code-lens
安装完成后再次运行 
cclens trace --help 2>&1
确认可用。
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
    是唯一可信来源。不打开浏览器 UI，不猜测 raw log 路径。
  • 始终使用 
    -f json
    。将 CLI 输出视为结构化数据，而非自然语言。
  • 默认选择能回答用户问题的最窄范围 — 先看 
    lead
    或单个 subagent，必要时分别导出两者对照。
  • --debug
    仅在需要排查归因统计、log 文件路径或 per-agent 工具调用分布时使用，常规分析不添加。
  • 匹配到多个 session 时，用 
    startedAt
    、
    context
    和 
    status
    区分后再继续。
  • 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. 列出候选 Session

1. List Candidate Sessions

bash
cclens trace list -f json
参数用途
--query <text>
匹配 sessionId、context、status、agents 或 agent 名称
--since <iso-date>
仅返回指定 ISO 8601 时间戳之后的 session
--limit <n>
限制返回数量（在构建摘要前截断，非正整数会触发 
INVALID_ARGUMENT
）
--max-preview <n>
截断 context、status、does、outcome 等摘要字段（默认 120–220 字符不等）
如果 
cclens trace list
返回空列表，或列表中找不到用户提及的 session，说明该会话不是通过 cclens 启动的 Claude Code，无法获取 trace 数据。此时应直接告知用户：该会话缺少 trace 记录，可能是未使用 cclens 启动，建议后续通过 cclens 启动 Claude Code 以便捕获 trace。
每个 session 的关键字段：
  • sessionId
    — 
    show
    和 
    export
    的主键
  • startedAt
    — 区分同一任务的多次运行
  • context
    — 首条模型 thinking 或 fallback 会话上下文，用于确认目标 trace
  • status
    — session 当前或最终结果摘要
  • agents
    — agent 数量概览，如 
    lead + 6 subagents
bash
cclens trace list -f json
ParameterPurpose
--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)
If 
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. 查看 Session 中的 Agent

2. View Agents in the Session

bash
cclens trace show --session <sessionId> -f json
每个 agent 的关键字段：
  • id
    — 传给 
    export --agent
  • role
    — 
    lead
    或 
    subagent
  • name
    — 紧凑可识别名称，subagent 格式为 
    <type> · <description>
  • does
    — 该 agent 被派去做什么
  • outcome
    — 该 agent 交付了什么
按用户意图选择导出目标：
用户意图导出目标匹配方式
排查整体流程、任务编排问题
--agent lead
直接指定
调查某个 subagent 的行为或失败原因
--agent <id>
按 
name
匹配，歧义时看 
does
对比 Lead 和 Subagent 的协作分别导出 
--agent lead
和 
--agent <id>
先用 
lead
看调度，再用 subagent id 看执行
在运行 
show
之前先读取 
list
输出中的 
context
和 
status
，避免对错误 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 IntentExport TargetMatching 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 SubagentExport 
--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. 导出 Trace 为 Markdown

3. Export Trace as Markdown

bash
cclens trace export --session <sessionId> --agent <agentId|lead> -f json
值范围
lead
仅主 Agent
<id>
指定 subagent（id 来自 
show
输出）
指定输出路径：
bash
cclens trace export --session <sessionId> --agent <id> --out /tmp/cclens-<session>-<agent>.md -f json
返回的 JSON 中 
markdownPath
是下一步要读取的绝对路径，同时返回 
agent.does
和 
agent.outcome
，读取前先确认导出对象与目标一致。
未指定 
--out
时，默认输出到 
~/.claude-code-lens/exports/trace-<session前8位>-<agentId>.md
。
bash
cclens trace export --session <sessionId> --agent <agentId|lead> -f json
ValueScope
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. 读取并分析 Markdown

4. Read and Analyze Markdown

对 
markdownPath
用 
Read
工具读取。
分析重点：
  • 范围过大、重复或可避免的工具调用
  • does
    与实际行为不一致的 subagent
  • 因 Skill 指令不清晰导致的过长 thinking 路径
  • Skill 中缺失的约束、决策规则或示例
  • 可减少步骤、工具调用或 agent 交接的机会
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

所有错误以结构化 JSON 返回。读取 
error.code
决定恢复路径，不要解析 
message
做判断。
错误码触发条件恢复方式
NO_LOGS
raw_logs/
中没有捕获到会话		提示用户先运行 CCLens 捕获一次会话
列表为空
trace list
返回空数组，或找不到用户提及的 session		告知用户：该会话不是通过 cclens 启动的，无法获取 trace。建议后续使用 cclens 启动 Claude Code
SESSION_NOT_FOUND
指定的 
sessionId
在所有 log 中都不存在		重新运行 
trace list -f json
，选择有效的 
sessionId
AGENT_NOT_FOUND
指定的 agent id 在 session 中不存在重新运行 
trace show --session <id> -f json
，选择有效的 
agents[].id
EXPORT_FAILED
Markdown 写入失败用 
--out /tmp/<name>.md
重试，或报告路径/权限问题
UNSUPPORTED_FORMAT
使用了 
json
/
yaml
/
yml
之外的格式		使用 
-f json
或 
-f yaml
INVALID_ARGUMENT
--limit
或 
--max-preview
不是正整数		检查参数值，传入有效正整数
All errors are returned as structured JSON. Read 
error.code
to determine the recovery path; do not parse 
message
for judgment.
Error CodeTrigger ConditionRecovery 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 sessionRe-run 
trace show --session <id> -f json
and select a valid 
agents[].id
EXPORT_FAILED
Markdown writing failedRetry 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

汇报结果时包含以下要素，缺一不可：
  • 目标 session：
    sessionId
    和 
    startedAt
  • 目标 agent：
    id
    、
    role
    、
    name
    、
    does
  • 证据：导出 Markdown 中的简短引用片段，不凭空断言
  • 建议：具体的 Skill 或工作流修改方案，而非泛泛的观察
  • 置信度：说明是否使用了 
    --debug
    ，以及分析了 
    lead
    、单个 subagent，还是两者都分析了
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