How to Export earendil pi Sessions to HTML: Complete Guide

Run pi --export /path/to/file.html after your REPL session to generate a standalone, syntax-highlighted HTML transcript, or invoke exportSessionToHtml() programmatically from the coding-agent package.

The earendil-works/pi repository provides a built-in HTML exporter that transforms JSON session logs into self-contained web pages. Understanding how to export earendil pi sessions to HTML allows you to archive terminal output—including AI conversations, tool results, and ANSI colors—in a portable format suitable for sharing or documentation.

How the HTML Export Pipeline Works

The export process traverses six distinct stages across the packages/coding-agent module. Each component handles a specific transformation from raw session data to final markup.

CLI Argument Parsing

The entry point resides in packages/coding-agent/src/cli/args.ts, which registers the --export flag and captures the target file path. When you append --export to your command, the parser validates the path and forwards it to the session manager.

Session Orchestration

The AgentSession.exportToHtml method—implemented around line 2969 in packages/coding-agent/src/core/agent-session.ts—serves as the coordinator. It verifies that the session exists on disk (in-memory sessions cannot be exported) and initializes the HTML generation workflow.

Core HTML Generation

The ExportHtml class in packages/coding-agent/src/core/export-html/index.ts walks through the session's message history. It processes metadata, user prompts, assistant replies, and tool outputs, assembling them into a structured document.

ANSI-to-HTML Conversion

Terminal colors and text styles convert via the parser in packages/coding-agent/src/core/export-html/ansi-to-html.ts. This module transforms ANSI escape sequences—such as \x1b[31m for red text—into safe HTML spans with inline CSS styles.

Tool Rendering Support

For sessions containing custom tool calls that implement TUI renderers, packages/coding-agent/src/core/export-html/tool-renderer.ts executes the renderer, captures the ANSI output, and feeds it through the conversion pipeline. If a renderer fails, the system falls back to a generic JSON view rather than aborting the export.

Template Assembly

The final document injects content into static templates located via getExportHtmlTemplateDir in packages/coding-agent/src/config.ts. The resulting file is written atomically and contains no external dependencies.

Exporting Sessions from the Command Line

To export interactively, first record your session using the TUI, then specify the export path:

# Launch the interactive REPL

pi

# Quit the REPL, then export the session you just recorded

pi --export ~/reports/session-2024.html

The CLI validates that the session file exists before invoking the HTML pipeline. If you attempt to export an unsaved, in-memory session, the tool returns a clear error message instructing you to persist the data first.

Programmatic HTML Export

For automation scripts or custom workflows, import the export function directly from the source:

import { exportSessionToHtml } from "pi/packages/coding-agent/src/core/export-html";

const sessionPath = "/home/user/.pi/session.json";
const outputPath  = "/var/www/docs/session.html";

await exportSessionToHtml(sessionPath, outputPath);
console.log(`Exported to ${outputPath}`);

This wrapper loads the JSON session, instantiates the rendering pipeline, and writes the complete HTML document using the bundled templates.

Rendering Custom Tool Output

Tools that expose a renderTui method automatically benefit from rich HTML export. The exporter attempts to execute the renderer and convert the terminal output:

// Example tool definition with TUI support
export const MyAnalyzer = {
  name: "analyzer",
  renderTui: (data) => {
    // Returns colored terminal output
    return `\x1b[34mAnalyzing ${data.length} files...\x1b[0m`;
  }
};

No additional configuration is required; simply providing the renderTui method enables the tool-renderer.ts module to embed styled output in the final HTML.

Low-Level ANSI Conversion

If you need to convert raw ANSI strings outside a full session context, use the standalone converter:

import { ansiToHtml } from "pi/packages/coding-agent/src/core/export-html/ansi-to-html";

const terminalOutput = "\x1b[32mSuccess\x1b[0m: Build completed";
const htmlFragment = ansiToHtml([terminalOutput]);
// Returns: '<span style="color:#00aa00">Success</span>: Build completed'

This utility is useful for debugging or for embedding isolated command output into other documents.

Summary

• The --export flag triggers the pipeline defined in packages/coding-agent/src/core/export-html/index.ts
• AgentSession.exportToHtml validates that sessions exist on disk before processing
• ansi-to-html.ts converts terminal colors into inline CSS while escaping all content to prevent XSS
• Custom tool renderers execute automatically but degrade gracefully to JSON on failure
• Templates are retrieved via getExportHtmlTemplateDir in packages/coding-agent/src/config.ts

Frequently Asked Questions

Can I export a session that is still in memory?

No. The exporter requires a persisted JSON session file. If you attempt to export before saving, AgentSession.exportToHtml throws an error indicating that only on-disk sessions are supported.

What happens if a custom tool renderer crashes during export?

The tool-renderer.ts module wraps renderer execution in a try-catch block. Upon failure, it substitutes a safe JSON representation of the tool output, allowing the remainder of the session to export successfully.

Is the generated HTML safe to share with untrusted viewers?

Yes. The ansi-to-html.ts converter escapes all HTML-sensitive characters before injection, and the templates contain no JavaScript or external resources. The output is a self-contained, static document safe for public distribution.

Can I customize the appearance of the exported HTML?

Yes. The exporter reads templates from the directory returned by getExportHtmlTemplateDir in packages/coding-agent/src/config.ts. Modifying the HTML or CSS files in that directory before running the export allows you to customize styling, fonts, and layout while preserving the content injection logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}