Conversation Analyzer

Overview

AI Conversation Analyzer is an npm-distributed tool for debugging and understanding AI agent conversations — OpenCode and (by design) any future platform. The project is two halves maintained together: a local dashboard server that consumes agent data, and this website, which has to market the tool, explain it, and document it deeply. This case study is about that second half.

The site is deliberately boring about infrastructure and opinionated about craft: pure HTML/CSS/JS with no build step, an 11-file design-token CSS system, a docs engine that renders ~30 Markdown pages with search and addresses for each one, and a dark developer aesthetic that sells the product's own dashboard before a single screenshot loads.

The product

The product defines what the site has to communicate, so it's worth getting precise about it:

• CLI + dashboard: npm install -g ai-conversation-analyzer gives you the conversation-analyzer command, which serves a local dashboard at http://127.0.0.1:4474.
• OpenCode plugin: conversation-analyzer init interactively registers it as an OpenCode plugin — writing "plugin": ["ai-conversation-analyzer"] into ~/.config/opencode/opencode.jsonc — so the dashboard auto-starts whenever OpenCode loads it.
• Normalized data model: every backend connector produces the same ConversationSpec shape (versioned, with session, assistant, metrics, messages, timeline, tools, and background calls kept separate). A parser registry maps source names — opencode, cursor, claude — to parser functions, so adding a platform is "connector + datasource + parser", nothing else.
• Three ways in: upload a JSON export, load a bundled ~1 MB demo session, or connect to a live backend and enable Live polling (4-second auto-refresh with in-place updates on the Messages, Tools, and Timeline tabs).
• Privacy by architecture: everything runs in the browser. Offline-first, no data ever leaves the machine — the site's leading promise and the easiest way to capture trust for a debugging tool.
• Release history: shipped to npm through v1.2.x — quiet-logs and a clean-uninstall path were the headline features after v1.1.0, and each release is reconciled with the site's changelog.

Site structure & design

A multi-page site rather than a single scroller, because a developer tool needs dedicated spaces for features, docs, community, contribution, changelog, and roadmap — each with its own URL.

• Pages: landing (index), features, docs, community, contribution, changelog, roadmap, about, plus a custom 404 — all sharing the same header/footer partials and design system.
• Typography & icons: Inter + JetBrains Mono (the classic "engineer's editorial" pairing), and Font Awesome 6.7.2 for iconography — no icon imagery to maintain.
• Hero as a product demo: instead of a stock image, the landing hero is a hand-built mock dashboard — an animated title-bar, stat counters (tokens / tool calls / reasoning) that count up on load, and data-width bars for input/output/reasoning/cache. The product story is told before any screenshot appears.
• Persuasion sections: nine feature cards, a four-step "Export → Load → Parse → Explore" how-it-works strip, a "why it exists" comparison band, a stats band, a community grid, and a CTA — all static HTML/CSS animated by a tiny reveal-on-scroll script with reduced-motion support.

Dashboard features

The dashboard itself is the site's best sales material, so the features page pairs eight real product screenshots with what each view is for:

• Overview: session info, summary stats, token metrics, and a computed health score.
• Timeline: a chronological event stream — message, reasoning, tool start/end events — with filter chips.
• Messages & Tools: sortable AG Grid tables; clicking a row opens a detail panel with full expandable content (payloads, duration, status).
• Insights: seven interactive Plotly charts — token distribution, latency breakdown, Gantt-style views — plus p50/p95 latency percentiles and context-accumulation curves that reveal when a session is degrading.
• Cost analysis: spend tracked per session, per turn, and per tool call, including hidden background calls (title-generation, compaction) kept separate from visible conversation tokens.

The docs system

The docs are content-driven rather than hand-authored pages — a small Markdown engine instead of a dozen hardcoded HTML files:

• One source of truth: docs/sidebar.json defines the tree — Getting Started, Importing Data, Configuration, Understanding Reports (eight pages), Providers, Architecture, API Reference, and FAQ — and writing a doc is just adding a Markdown file plus a sidebar entry.
• Markdown on render: the docs page pulls Markdown, renders it with marked.js, and uses custom renderers to add things Markdown can't: tabbed install blocks (global / npx / from source), code blocks with copy buttons and language headers, and styled callout notes.
• Keyboard-first navigation: Ctrl+K opens site-wide search over the sidebar, and every page gets prev/next paging plus its own addressable path via URL state — so documentation feels like real documentation, not a README in a browser.
• Release-linked: the changelog page is reconciled with actual npm/GitHub releases (v1.1.0 → v1.2.0/v1.2.1), and the roadmap page is the promised future, not vague marketing.

Architecture

Zero build step, zero dependencies at runtime. The site is static pages plus a few small scripts, and its discipline is configuration over repetition.

• Shared partials: header and footer are injected everywhere by include.js, so nav, mobile menu, download buttons, and footer never drift between pages.
• One config, everywhere: config.js holds a single APP_CONFIG (repo owner/name, releases URL, contact email), and links are written as data-github/data-email attributes that include.js resolves at load — every GitHub link on the site is valid by construction.
• Split CSS: 11 focused files — tokens, base, background, navigation, components, layout, footer, home, pages, animations, responsive — following a token → base → layout → component cascade, so themes and layout changes stay local.
• Small JS surface: four modules — config.js, include.js, main.js, markdown.js/docs.js — each with one job.
• Real iteration in git: the history shows the site evolving with the product — a custom Markdown parser replaced by marked.js CDN for reliability, Ctrl+K search and prev/next nav added, real screenshots swapped in, download buttons pushed into the mobile menu, and responsive fixes for the hero install block.

Deployment & SEO

• Hosted on GitHub Pages (conversation-analyzer.github.io) with a .nojekyll file and a custom 404 that matches the site's design.
• Open Graph and Twitter card meta, keyword meta, and descriptive titles on every page; preconnect hints for the font CDNs to keep first paint quick.
• Cross-linked with the npm ecosystem: the download button targets the latest GitHub release asset, and community links resolve to the repo's issues, pulls, discussions, and releases from a single config value.
• Documentation and product pages agree with the package README, so "Install" works verbatim wherever a prospective user lands.

Status & roadmap

The current build advertises Download v1.2.0 (with the v1.2.1 changelog documented), and the site carries a roadmap as a real page with committed directions: more platform connectors (the architecture's parser-registry design makes this cheap), deeper analytics — the product claims 8+ charts and 100% browser-based operation today. Positioned in the project list as in development, it's the most product-like build in the portfolio: a tool, its documentation, and its marketing site that have to move together without a build system forcing consistency.