Skip to content

Add per-message timestamps to markdown and HTML output#57

Open
madorian wants to merge 1 commit into
ZeroSumQuant:mainfrom
madorian:add-per-message-timestamps
Open

Add per-message timestamps to markdown and HTML output#57
madorian wants to merge 1 commit into
ZeroSumQuant:mainfrom
madorian:add-per-message-timestamps

Conversation

@madorian
Copy link
Copy Markdown

Summary

The JSONL source data already contains ISO 8601 timestamps on every message entry (entry.get("timestamp")), and extract_conversation() correctly preserves them in the conversation dicts. However, save_as_markdown() and save_as_html() only use the first message's timestamp for the file-level header metadata -- individual message headings have no temporal information.

This PR appends the formatted timestamp to each message heading:

  • Markdown: ## 👤 User [2026-05-18 21:00:05]
  • HTML: inline <span> after the role label, styled in subdued gray

When a message has no timestamp field, the heading renders exactly as before (no brackets), maintaining backward compatibility.

Motivation

Per-message timestamps enable correlating conversation events with external systems (git commits, file modifications, CI logs) without parsing raw JSONL. This is especially valuable for forensic analysis across concurrent sessions.

Changes

  • Added _format_timestamp() static method for consistent ISO-to-display formatting
  • Updated save_as_markdown() to include [timestamp] on each role heading
  • Updated save_as_html() to include timestamp span on each role heading

Example output

## 👤 User [2026-05-18 21:00:00]

Hello

---

## 🤖 Claude [2026-05-18 21:00:05]

Hi there

---

## 👤 User

Message without timestamp (renders cleanly)

The JSONL source data already contains ISO 8601 timestamps on every
message entry, but save_as_markdown() and save_as_html() were only
using the first message's timestamp for the file header metadata.

This adds the timestamp to each message heading in the exported output:
- Markdown: ## 👤 User [2026-05-18 21:00:05]
- HTML: inline <span> after the role label

When a message has no timestamp, the heading renders without one,
maintaining backward compatibility with older JSONL files.

Per-message timestamps enable:
- Correlating conversation events with external logs
- Disambiguating ordering across concurrent sessions
- Forensic analysis without parsing raw JSONL
@ArchiLantern
Copy link
Copy Markdown

Great PR! This per-message timestamp is very helpful.

One suggestion to make it even better: add timezone conversion for users outside UTC+0.
For example, a --timezone Asia/Shanghai (or --offset +8) option that displays timestamps in local time.
The JSONL stores UTC, but many users (like me) want to see Beijing time directly in the exported markdown/HTML.

Would you be open to adding that, or should I file a separate issue for it?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants