| name | view-trajectory |
| description | Open a Claude Code session trajectory (.jsonl) in the cc-trajectory-viewer web UI to inspect the timeline, clustered tool calls, and code diffs. Can also generate an annotations sidecar that adds one-line summaries for each tool-call cluster and translations of every message into a target language. Use when the user asks to visualize, view, open, summarize, or translate a trajectory / session log. |
View a Claude Code trajectory
@xinyuehtx/cc-trajectory-viewer renders a Claude Code trajectory (.jsonl
session log) as a web UI: a message Timeline (with consecutive tool calls
grouped into collapsible clusters), and a separate Diffs tab showing every
file change as a unified or split code diff.
The trajv command is provided by the package. Prefer npx -y @xinyuehtx/cc-trajectory-viewer ….
1. Just view a trajectory
npx -y @xinyuehtx/cc-trajectory-viewer "<path-to-session>.jsonl"
Add --no-open for headless, -p <port> to choose a port. Run with no path to
open drag-and-drop upload mode.
Locating the file
Sessions live at ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl, where
<encoded-cwd> is the project's absolute path with / and . replaced by -.
To open the newest session for a project directory:
DIR="$HOME/.claude/projects/$(echo "$PWD" | sed 's#[/.]#-#g')"
FILE=$(ls -t "$DIR"/*.jsonl 2>/dev/null | head -1)
npx -y @xinyuehtx/cc-trajectory-viewer "$FILE"
If the user names a specific file or session id, use that directly.
2. Add summaries and/or translations (annotations)
The viewer can overlay a sidecar annotations file (<file>.trajv.json) that
adds, per stable id:
- a one-line summary for each cluster of consecutive tool calls (shown in the
cluster header),
- a one-line summary for each collapsed tool-execution message (assistant text
that starts with "Executed …" / "Running …" — a
text unit that has a summary
field) and for each subagent block (a subagent unit), shown in their
collapsed headers, and
- a translation of each user/assistant message into a target language (shown
beneath the original text).
Workflow — you (the agent) fill in the annotations:
-
Generate the scaffold. This writes a .trajv.json next to the trajectory
with every text unit (with its original text), every tool-call cluster
(with the tool names), and every subagent block already enumerated and
correctly keyed:
npx -y @xinyuehtx/cc-trajectory-viewer extract "<file>.jsonl" --lang "<target language>"
Use the language the user asked for (e.g. 简体中文, English, 日本語); omit
--lang if they only want summaries.
-
Read the scaffold (<file>.jsonl.trajv.json). It looks like:
{
"version": 1,
"targetLang": "简体中文",
"units": [
{ "type": "text", "id": "<uuid>", "role": "user", "original": "…", "translation": "" },
{ "type": "text", "id"
In the UI, cluster / subagent / tool-execution summaries appear in their
collapsed headers, and translations appear under each message (toggle "Show
translations" in the sidebar).
Notes
npx fetches the published package, which bundles the built HTML — no build step.- From a local clone, run
pnpm install && pnpm build first, then node bin/cli.js ….
- Everything is served from
localhost; nothing is uploaded.
