Session Viewer
Use when asked to view, export, inspect, or share a Codex, Claude Code, OpenClaw, or Pi session transcript in a browser.
Commands
Resolve SESSION_VIEWER_SKILL_DIR to the directory containing this SKILL.md.
Use that installed source for commands, independent of the current repository.
When the session path is not known and the agent-transcript skill is available, use it first to find the likely JSONL session:
Resolve TRANSCRIPT_SKILL_DIR from that skill's actual installation before running:
"$TRANSCRIPT_SKILL_DIR/scripts/agent-transcript" find \
--query "$USER_GOAL_OR_TITLE $BRANCH_OR_URL" \
--cwd "$PWD" \
--since-days 14Pick the highest-confidence file result, then render it with session-viewer.
Render with the resolved installation:
node "$SESSION_VIEWER_SKILL_DIR/scripts/session-viewer.ts" <session.jsonl> --out /tmp/session.html --openUseful modes:
node "$SESSION_VIEWER_SKILL_DIR/scripts/session-viewer.ts" <session.jsonl> --out session.html
node "$SESSION_VIEWER_SKILL_DIR/scripts/session-viewer.ts" <session.jsonl> --raw --out session.html
node "$SESSION_VIEWER_SKILL_DIR/scripts/session-viewer.ts" --blank --out viewer.html --openDefaults:
- detects
codex,claude, orpi-openclaw - embeds normalized session data into one HTML file
- keeps tool input/output text in the DOM so browser search can find it
- reads the complete session file, preserving full history in both export modes
--rawembeds the original JSONL and lets the browser parse it--blankcreates a reusable file-picker viewer
For an explicitly partial export, use --max-read-bytes N with a positive integer byte limit (for example, --max-read-bytes 8388608 for 8 MiB). Oversized files retain the head and tail, with a visible omission warning in the CLI and exported viewer. Truncated boundary records may be omitted; --raw embeds only the retained JSONL. Files at or below the limit remain complete. Short reads are retried; an unexpected end of file fails the export instead of reporting a complete read.
This opt-in read limit applies only to CLI file exports. The browser's file picker continues to load complete files.
Where Sessions Live
Codex:
find "${CODEX_HOME:-$HOME/.codex}/sessions" -name 'rollout-*.jsonl' -type f | sort
ls -t "${CODEX_HOME:-$HOME/.codex}"/sessions/*/*/*/rollout-*.jsonl | headCurrent OpenClaw stores session indexes and transcripts in per-agent SQLite databases. Use native session discovery:
openclaw sessions --agent "<agentId>" --jsonThis lists sessions; it does not export a JSONL transcript. The viewer requires a supported JSONL transcript, not a SQLite database or session-list JSON. Use OpenClaw's native session view when no compatible JSONL export is available. See the OpenClaw sessions reference.
Legacy OpenClaw JSONL:
AGENT_ID="<agentId>"
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
ls -t "$SESSION_DIR"/*.jsonl | head
find "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents" -path '*/sessions/*.jsonl' -type f | sortOnly legacy file stores use sessions.json beside those transcripts to map session keys to ids.
For standalone Pi, select its actual JSONL transcript rather than assuming the OpenClaw directory layout.
Claude Code:
find "$HOME/.claude/projects" -name '*.jsonl' -type f | sort
ls -t "$HOME/.claude/projects"/**/*.jsonl | headSome Claude installs also keep exported JSON/JSONL under project-specific cache folders; prefer the newest JSONL with the target repo path in its parent folder.
Development
Scripts are native Node TypeScript. Keep them erasable:
- ok: types, interfaces, unions,
satisfies - avoid: enums, namespaces, decorators, parameter properties
- no tsconfig path aliases; use relative imports
Importer ownership:
scripts/importers/codex.ts: Codex rollout JSONLscripts/importers/claude.ts: Claude Code JSONLscripts/importers/pi-openclaw.ts: Pi/OpenClaw session JSONL
Validate:
npm ci --ignore-scripts
npm run typecheck
node --test skills/session-viewer/scripts/session-viewer.test.ts
scripts/validate-skills