miriad-viz

Animated timeline visualization for Miriad channel retrospectives — showing how AI agents and humans collaborate over time.

Turn 60+ hours of channel activity into a cinematic replay: agents joining, communicating, shipping code, and hitting milestones.

What It Does

Given extracted channel data (commits, PRs, messages, artifacts), miriad-viz produces:

• Interactive viewer — scrub through time, watch the team form and build
• Video export — render to MP4 via Remotion for sharing

The visualization shows:

• Agent nodes that pulse with activity
• Communication beams traveling between agents
• Artifact, PR, and commit timelines
• Phase backgrounds and milestone markers
• Trust arc and narration overlays

Quick Start

# Install dependencies
pnpm install

# Run extraction (requires gh CLI authenticated)
pnpm extract --repo owner/repo --out ./data

# Transform to viz-ready format
pnpm viz ./data

# Launch interactive viewer
pnpm dev

Data Pipeline

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Extraction │───▶│  Transform  │───▶│   Engine    │───▶│  Renderer   │
│             │    │             │    │             │    │             │
│ gh CLI      │    │ normalize   │    │ frame state │    │ R3F + drei  │
│ Miriad MCP  │    │ enrich      │    │ per tick    │    │ zero logic  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
     │                   │                  │
     ▼                   ▼                  ▼
  RawData           VizData            FrameState
  (8 JSON files)    (renderer-ready)   (pure function)

Data Contracts

| Layer | Input | Output | Purpose | |-------|-------|--------|---------| | Extraction | GitHub API, Miriad MCP | RawData (8 JSON files) | Gather raw data | | Transform | RawData + CurationData | VizData | Normalize, enrich, compute layout | | Engine | VizData + time | FrameState | Pure getFrameState(t, data) | | Renderer | FrameState | Pixels | Declarative R3F scene |

See docs/data-contracts.md for full TypeScript schemas.

CLI Commands

# Extraction — pull data from GitHub
pnpm extract --repo owner/repo --out ./data

# With Miriad channel data (pre-extracted via MCP)
pnpm extract --repo owner/repo --out ./data \
  --chat-input ./raw-messages.json \
  --artifact-input ./raw-artifacts.json

# Transform — process into viz-ready format
pnpm viz ./data                    # Output to ./data/output/
pnpm viz ./data --out ./custom-dir # Custom output directory

See docs/extraction-guide.md for step-by-step data extraction.

Development

pnpm dev          # Vite dev server (http://localhost:5173)
pnpm test         # Run tests
pnpm lint         # Biome check
pnpm lint:fix     # Biome auto-fix
pnpm build        # Production build

Architecture

4-layer pipeline with strict separation of concerns:

1. Extraction — Miriad MCP + gh CLI produce 8 JSON source files
2. Transform — Normalize, enrich, compute agent layout → VizData
3. State Engine — getFrameState(t, vizData) returns FrameState (pure function)
4. Renderer — R3F/drei presents FrameState (zero data processing)

Key principle: Renderer does zero logic. All animation is pre-computed by the engine. The renderer is a dumb display layer that reads FrameState and draws it.

Stack

• Vite — bundler + dev server
• React Three Fiber + drei — declarative 3D rendering
• Remotion — video export
• zustand — state management
• Biome — lint + format
• Vitest — tests

Documentation

| Guide | Description | |-------|-------------| | Data Contracts | TypeScript schemas for RawData, CurationData, VizData | | Extraction Guide | How to extract data from GitHub + Miriad | | Curation Guide | Editorial content: phases, milestones, quotes | | FEATURES.md | Feature tracker with implementation status |

Source Data Files

The extraction pipeline produces 8 JSON files:

| File | Source | Description | |------|--------|-------------| | git-commits.json | GitHub API | Commit history with stats | | pr-details.json | GitHub API | Pull request metadata | | pr-agent-map.json | Heuristics | Maps PRs to agent callsigns | | chat-activity.json | Miriad MCP | Channel activity summary | | artifact-data.json | Miriad MCP | Board artifact inventory | | timeline-events.json | Processing | Unified event stream | | retro-page-data.json | Editorial | Phases, milestones, trust arc | | retro-page-quotes.json | Editorial | Curated quotes |

TypeScript types for all files: src/transform/source-types.ts

License

MIT