Index of every page on this site: llms.txt
All skills
openclaw avatar

/session-viewer

@0a5ba4b
by openclawopenclaw/agent-skills1.1k stars
126
Run it yourself

Render Codex, Claude Code, OpenClaw, or Pi session JSONL transcripts as a searchable, shareable single-file HTML viewer.

Use this Skill: https://skilld.dev/gh/openclaw/agent-skills/session-viewer

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈34 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈127 more on demand in 3 files.

Description uses 1.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈137 characters, or 1.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 14

Pick 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 --open

Useful 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 --open

Defaults:

  • detects codex, claude, or pi-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
  • --raw embeds the original JSONL and lets the browser parse it
  • --blank creates 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 | head

Current OpenClaw stores session indexes and transcripts in per-agent SQLite databases. Use native session discovery:

openclaw sessions --agent "<agentId>" --json

This 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 | sort

Only 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 | head

Some 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 JSONL
  • scripts/importers/claude.ts: Claude Code JSONL
  • scripts/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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts15d3 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill provides a tool for rendering AI agent session transcripts (JSONL) as searchable HTML files. It is a legitimate utility that implements proper security measures like HTML sanitization to prevent cross-site scripting (XSS) when viewing transcripts. It handles local file paths safely and does not perform any unauthorized data exfiltration or remote code execution.

  • Socket15d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

Signed by skilld at 0a5ba4b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for openclaw/agent-skills/session-viewer