# How Agentsview Session Export Works for HTML, Markdown, and GitHub Gist

> Explore Agentsview's session export. Convert chat sessions to HTML, Markdown, or GitHub Gist. Learn how the export feature processes SQLite messages for various formats.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Agentsview's session export feature converts chat sessions into self-contained HTML pages, structured Markdown documents, or GitHub Gists by processing SQLite-stored messages through format-specific generators in [`internal/server/export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go) and [`internal/server/export_markdown.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export_markdown.go).**

The `kenn-io/agentsview` repository provides a Go-based session management system for AI agent interactions. Its **session export** functionality operates entirely server-side, transforming conversation data from a SQLite backend into portable formats via HTTP handlers or the CLI's `agentsview export` command. The implementation spans the server's export handlers, format-specific generators, and CLI frontend components.

## Export Architecture and Data Flow

The export pipeline follows a consistent sequence across all formats, beginning with database retrieval and ending with format-specific serialization.

### Session Data Retrieval

Every export request triggers database queries in [`internal/server/export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go). The `ExportHandler` calls `s.db.GetSession(ctx, sessionID)` to fetch session metadata, followed by `s.db.GetAllMessages(ctx, sessionID)` to retrieve the complete message history. These functions are defined in [`internal/db/session_export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/session_export.go) and provide the raw data required for all subsequent formatting operations.

### Format Selection

The handler routes requests based on the `format` query parameter using a switch statement that supports three values: `html`, `md` (Markdown), or `gist`. This routing logic resides in [`internal/server/export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go) and determines whether to invoke `generateExportHTML`, `generateExportMarkdown`, or the Gist publishing workflow.

## HTML Export Implementation

The **HTML export** produces a standalone, self-contained document that replicates the application's transcript view.

### Template-Based Generation

**`generateExportHTML`** constructs the output by applying the `exportTemplateStr` template to a filtered message set. This template bundles CSS and JavaScript toggles, ensuring the exported file renders identically to the on-screen view without external dependencies.

### Message Filtering and Content Processing

Before template application, **`filterExportHTMLMessages`** strips internal "goal-context" messages that should not appear in exported transcripts. Each remaining message is transformed into an **`exportMessage`** struct containing the role, timestamp, and HTML-escaped content. This escaping prevents XSS vulnerabilities while preserving text formatting.

## Markdown Export Implementation

The **Markdown export** generates a deterministic, structured document capable of representing complex conversation trees, including child sessions spawned by tool calls.

### Recursive Session Tree Loading

Unlike HTML export, Markdown generation supports hierarchical session structures. **`generateExportMarkdown`** in [`internal/server/export_markdown.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export_markdown.go) calls **`loadExportSessionTree`** to recursively fetch parent and child sessions based on the requested depth. The CLI accepts `--depth all` for complete trees or `--depth 1` for direct children only.

### Segment Parsing and Semantic Preservation

Each message undergoes processing by **`parseMarkdownSegments`**, which decomposes content into typed segments including plain text, thinking blocks, code blocks, and tool calls. Rather than emitting raw Markdown immediately, the generator wraps these segments in XML-style tags (`<message>`, `<tool_call>`, `<code_block>`). This intermediate representation preserves semantic structure for frontend re-importation while rendering as clean Markdown in standard viewers.

## GitHub Gist Publishing

The **Gist export** combines HTML generation with GitHub API integration to create hosted, shareable transcripts.

### Token Resolution Strategy

When processing `gist` format requests, **`resolveGitHubToken`** implements a hierarchical authentication strategy. The system first checks the `--token` CLI flag, then falls back to the `AGENTSVIEW_GITHUB_TOKEN` environment variable. For localhost deployments specifically, it executes `gh auth token` to extract credentials from the GitHub CLI.

### API Integration and Response Generation

**`createGist`** constructs a JSON payload containing the HTML content, description, and public/private status, then POSTs to `https://api.github.com/gists`. The **`publishExportHTML`** function orchestrates this process, returning a structured response that includes the `gist_url`, `raw_url`, and an HTML preview URL via `https://htmlpreview.github.io/?`.

## Command-Line Usage Examples

The [`cmd/agentsview/export.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/export.go) CLI frontend exposes these formats through the `agentsview export` command.

### Export to HTML

Generate a standalone HTML file suitable for offline viewing:

```bash
agentsview export --session-id 12345 --format html > session.html

```

This invokes `generateExportHTML` and writes the templated output to stdout.

### Export to Markdown with Depth Control

Capture complete conversation trees including tool-spawned sub-sessions:

```bash
agentsview export --session-id 12345 --format md --depth all > session.md

```

The `--depth` flag controls recursion levels, accepting `all` or specific integers.

### Publish to GitHub Gist

Create a public Gist containing the HTML representation:

```bash
agentsview export \
  --session-id 12345 \
  --format gist \
  --description "Agentsview session export" \
  --public

```

The command returns a JSON response:

```json
{
  "gist_id": "abcd1234",
  "gist_url": "https://gist.github.com/user/abcd1234",
  "view_url": "https://htmlpreview.github.io/?https://gist.githubusercontent.com/user/abcd1234/raw/session.html",
  "raw_url": "https://gist.githubusercontent.com/user/abcd1234/raw/session.html"
}

```

## Programmatic Integration

Developers can invoke export functions directly from Go applications:

```go
import (
    "context"
    "go.kenn.io/agentsview/internal/server"
    "go.kenn.io/agentsview/internal/db"
)

func exportToHTML(ctx context.Context, database *db.DB, sessionID string) (string, error) {
    sess, err := database.GetSession(ctx, sessionID)
    if err != nil {
        return "", err
    }
    msgs, err := database.GetAllMessages(ctx, sessionID)
    if err != nil {
        return "", err
    }
    // Note: GenerateExportHTML may require package exposure for external use
    return server.GenerateExportHTML(sess, msgs), nil
}

```

## Summary

- **Data Source**: All formats retrieve data from SQLite via `GetSession` and `GetAllMessages` in [`internal/db/session_export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/session_export.go).
- **HTML Generation**: `generateExportHTML` produces self-contained documents using the `exportTemplateStr` template with internal messages filtered by `filterExportHTMLMessages`.
- **Markdown Generation**: `generateExportMarkdown` handles recursive session trees via `loadExportSessionTree` and parses content into XML-tagged segments using `parseMarkdownSegments` in [`internal/server/export_markdown.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export_markdown.go).
- **Gist Publishing**: `createGist` and `resolveGitHubToken` in [`internal/server/export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go) manage GitHub API authentication and POST operations, with token resolution supporting CLI flags, environment variables, or GitHub CLI integration.
- **Security**: Automatic token resolution via `gh auth token` is restricted to localhost contexts only.

## Frequently Asked Questions

### How does Agentsview handle authentication for GitHub Gist exports?

Agentsview's `resolveGitHubToken` function implements a three-tier fallback system. It first checks for an explicitly provided CLI token, then examines the `AGENTSVIEW_GITHUB_TOKEN` environment variable. If neither is present and the server is running on localhost, it executes `gh auth token` to obtain credentials from the GitHub CLI. Remote servers require explicit token provision through flags or environment variables.

### What is the difference between HTML and Markdown exports in terms of session structure?

HTML exports flatten the session to a single transcript level, filtering out internal messages and producing a standalone page suitable for immediate viewing. Markdown exports preserve hierarchical session relationships through `loadExportSessionTree`, recursively including child sessions spawned by tool calls. The Markdown format uses XML-style tagging to preserve semantic message components like thinking blocks and tool calls, while the HTML format applies a template that mirrors the UI appearance.

### Can exported Markdown files be re-imported into Agentsview?

Yes. The Markdown export format intentionally uses an intermediate XML-style representation with tags like `<message>` and `<tool_call>` rather than pure Markdown. This structure preserves the complete semantic information of the conversation, enabling the frontend to parse and re-import sessions while still rendering cleanly as standard Markdown in other viewers.

### Where does the session export logic reside in the codebase?

The core export implementation is split between [`internal/server/export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export.go) (HTML generation and Gist publishing) and [`internal/server/export_markdown.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/export_markdown.go) (Markdown-specific logic). Database access functions live in [`internal/db/session_export.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/session_export.go), while the CLI frontend is implemented in [`cmd/agentsview/export.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/export.go). All processing occurs server-side, with the SPA or CLI merely triggering HTTP requests to the `ExportHandler`.