session-log-viewer

A Rust CLI tool that transforms .chat.md session transcripts into styled HTML and opens them in the browser. Designed for presenting and sharing AI-agent programming sessions with teams.

⚠️ Draft Specification — The Magaran format specification is pre-v1.0.0 and subject to breaking changes without notice. Do not depend on format stability until v1.0.0 is released.

What it does

view-session takes a .chat.md file — a structured transcript of a human-agent coding session — and renders it as a polished HTML page in your default browser. No intermediate files to manage, no servers to run.

view-session my-session.chat.md

The Magaran format

Session logs follow the Magaran chat log format, a markdown-compatible specification designed for:

• Plain-text readability — pleasant to read in any editor, even without rendering
• Unambiguous parsing — every structural element is deterministic
• Presentation use — course corrections, tool-call annotations, and visual structure make transcripts useful for team training

See specification/ for the full format specification.

Note for logger implementors

When participant content contains angle brackets (e.g., /proc/<pid>/exe, x < 5), prefer wrapping the content in a literal magic wand block and writing the raw characters:

<!-- Literal magic wand 🪄 -->
	we're talking about the hash of /proc/<pid>/exe right?
<!-- 🪄 -->

This is much more readable in plain text than HTML entity escaping (/proc/<pid>/exe). The parser automatically escapes the raw characters for the renderer. The magic wand must wrap the entire turn content. The only things that must be escaped inside a magic wand block are the magic wand markers themselves (<!-- Literal magic wand 🪄 --> and <!-- 🪄 -->) if they appear literally in the content.

Installation

Requires Rust (1.94+):

git clone https://github.com/magaransoft/session-log-viewer.git
cd session-log-viewer
cargo install --path .

We don't distribute pre-built binaries. This is a tool for programmers — you have the source, so read it (or have an agent review it) before you build. Building that habit matters more than saving a cargo install step.

Usage

# Open a session log in the browser
view-session path/to/session.chat.md

Themes

Two built-in themes with a dropdown switcher:

• Midnight — dark theme inspired by Discord, with a diagonal checkerboard texture background
• Daylight — light theme inspired by Charamel, with warm caramel tones and a linen grid texture

Project structure

session-log-viewer/
  .github/workflows/     # CI configuration
  specification/          # Magaran format specs (versioned)
    ABOUT.md              # Format purpose and design goals
    current-version.md    # Symlink to latest spec
    magaran-v0.1.0.md     # v0.1.0 specification
  src/
    ast.rs                # Data structures (ChatLog, Section, ToolCall, etc.)
    parser.rs             # Line-by-line state machine parser
    renderer.rs           # AST → self-contained HTML with embedded CSS/JS
    highlight.rs          # Syntax highlighting via syntect
    themes.rs             # Theme definitions (CSS custom properties)
    lib.rs                # Library crate root
    main.rs               # CLI entry point
  tests/
    fixtures/             # Real .chat.md files for integration testing
    parser_fixtures.rs    # Parser integration tests
  theme-samples/          # Static HTML mockups for visual reference

License

MIT