opencode-export

English | 中文

Export your opencode AI coding sessions to beautiful, self-contained HTML + JSON archives — with secret redaction, subagent inlining, token backfill, and an MCP server for agents.

Features

• Beautiful HTML output — Sticky headers with session metadata, collapsible tool-call and reasoning blocks, a slide-in TOC of user prompts, lazy syntax highlighting, KaTeX math rendering, and Mermaid diagram support.
• Secret redaction built-in — 18 patterns (OpenRouter, OpenAI, Anthropic, GitHub, AWS, Slack, GitLab, Google, Stripe, SendGrid, and more) are auto-masked. Add your own exact strings or regex patterns via config.
• Subagent inlining — When your session dispatched sub-agents (explore, general, code-reviewer), their full conversation is rendered inline at the dispatch point inside the parent session.
• 5-field token statistics — Input, output, reasoning, cache-read, and cache-write tokens are tracked per session. Older sessions with zero token data are backfilled by summing per-step usage from step-finish parts.
• Fully offline — Vendor assets (highlight.js, Mermaid, KaTeX, Marked) are downloaded once and bundled into the export. No CDN, no internet required to view.
• MCP server included — AI agents can call list_sessions, show_session, and export_sessions as native tools via the Model Context Protocol.
• Structured JSON archive — Alongside HTML, a data/sessions.json file preserves full, untruncated content (tool inputs/outputs, reasoning text) for programmatic analysis.

Quick Start

Prerequisites: Python 3.11+ and an existing opencode installation (the session database is auto-detected at %LOCALAPPDATA%\opencode\opencode.db on Windows, ~/Library/Application Support/opencode/opencode.db on macOS, or $XDG_DATA_HOME/opencode/opencode.db on Linux).

# Install
pip install git+https://github.com/ZelinZhou-THU/opencode-export.git

# See what projects and sessions exist in your opencode database
opencode-export list

# Export a project's sessions to a browsable HTML + JSON archive
opencode-export export --project my-project --out ./export

# Preview a single session's metadata
opencode-export show ses_xxxx

Open ./export/index.html in your browser. That's it — no server, no internet needed.

How it differs

Several tools exist for exporting opencode or Claude Code sessions, typically producing Markdown transcripts or basic HTML pages. opencode-export was built to address a few gaps encountered when archiving a full semester of AI-assisted development:

• Visual fidelity — Tool calls, reasoning blocks, code patches, and sub-agent threads are preserved in their original structure, not flattened to plain text.
• Safety by default — Secrets are masked before any HTML or JSON is written, using both built-in patterns and user-configured rules. The redaction engine is recursive (handles nested tool state) and idempotent (safe to run twice).
• Token reconstruction — opencode's database schema evolved over time; many older sessions have zero token data. opencode-export reconstructs usage by summing per-step token counts from step-finish message parts, and independently backfills cache fields.
• Agent-callable — Rather than only a human-facing CLI, the MCP server lets your AI agent discover, inspect, and export sessions on its own.

CLI Reference

Command	Purpose	Key flags
list	List projects or sessions in the database	--project DIR, --json
show <session-id>	Preview a session's metadata (title, model, token usage, etc.)	—
export	Generate HTML + JSON archive	--project DIR, --out DIR, --config FILE

Both HTML and JSON are generated by default. Use --no-html or --no-json to skip a format.

Configuration

All options can be set via YAML/JSON config file or CLI flags. See examples/config.example.yaml for the full schema:

db: auto                    # auto-detect, or explicit path
project:
  directory: "my-project"   # substring match on session.directory
select:
  min_messages: 30          # skip tiny sessions
  min_text_bytes: 10240     # skip near-empty sessions
  exclude: []               # session IDs to skip
output:
  dir: ./opencode_export
  formats: [html, json]
  vendor: download          # download | skip | copy-from
  timezone: Asia/Shanghai
redact:
  builtin: true             # 18 built-in secret patterns
  exact: []                 # your own [secret, replacement] pairs
  patterns: []             # your own [regex, replacement] pairs

MCP Server

Install with the [mcp] extra to let AI agents call the export tools directly:

git clone https://github.com/ZelinZhou-THU/opencode-export.git
cd opencode-export
pip install -e ".[mcp]"

Add to your opencode.json (or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "opencode-export": {
      "type": "local",
      "command": ["opencode-export-mcp"]
    }
  }
}

Three tools become available to the agent:

Tool	Purpose	Key params
list_sessions	List root sessions (by project)	project_directory, limit
show_session	Preview metadata + recent messages	session_id, message_limit
export_sessions	Generate HTML + JSON archive to disk	output_dir, session_ids, formats

See skill/SKILL.md for the agent-facing usage guide, or examples/opencode.json.example for a ready-to-use config.

Output Structure

opencode_export/
├── index.html            # Session index (stats grid + sortable table)
├── sessions/
│   ├── 01_2026-04-02_session-title.html
│   └── ...
├── data/
│   └── sessions.json     # Full archive (untruncated, structured)
└── assets/
    ├── style.css
    ├── renderer.js        # KaTeX / Mermaid / lazy highlight.js
    └── vendor/            # Offline JS libraries

Token Statistics

Each session and the index page display five token fields:

Field	Meaning
in	Input tokens (new prompt consumption)
out	Output tokens (model generation)
reasoning	Reasoning tokens (o1 / DeepSeek-R1 style thinking)
cache.read	Prompt cache hit reads
cache.write	Prompt cache writes

Total = sum of all five fields. This matches the billing granularity of OpenRouter, Anthropic, Google AI, and other providers where cache reads are billed as input tokens.

For older sessions where the database has zero token values, usage is reconstructed by summing per-step d["tokens"] across all step-finish parts.

Development

# Install in dev mode (CLI only)
pip install -e .

# Install with MCP server support
pip install -e ".[mcp]"

# Run tests
pytest tests/ -v

License

MIT