AI-powered retrospectives from your Slack history.
Transform years of conversations into a beautiful, browsable timeline of your team's story.

---

Prerequisites

• Bun runtime
• SQLite3 (usually pre-installed on macOS/Linux)
• For summary generation: Claude CLI (claude) or Amp CLI (amp)

Quick Start

1. Install dependencies

# Install summarizer dependencies
cd summarizer && bun install && cd ..

# Install webapp dependencies (server + client)
cd webapp && bun install && cd client && bun install && cd ../..

2. Get the database

Option A: Bootstrap from production (if you have k8s access, see deploy/README.md)

Option B: Import from Slack export

# Place your Slack export zip in input_data/
# Extract it to slack_export/

cd summarizer
bun run summarize --init-db
bun run summarize --import

# Fetch custom emoji (requires SLACK_TOKEN env var)
# This enables custom emoji to display correctly in the webapp
export SLACK_TOKEN="xoxb-your-slack-bot-token"
bun run summarize --fetch-emoji

3. Run the webapp

cd webapp
bun run dev

Visit http://localhost:5173

Generating Summaries

Summaries are generated in multiple steps, each requiring different AI providers.

Prerequisites

• Claude CLI (claude) or Amp CLI (amp) - for summaries and titles
• Gemini API key - for image descriptions (set GEMINI_API_KEY or GOOGLE_API_KEY env var)

Step 1: Generate Period Summaries

An AI agent (Claude or Amp) queries the SQLite database to write comprehensive summaries.

cd summarizer

# Generate a single month's summary
bun run summarize --type month --start 2021-03-01

# Preview without saving to database
bun run summarize --type month --start 2021-03-01 --preview

# Generate all months
bun run summarize --type month --all

# Use Amp instead of Claude
bun run summarize --type month --start 2021-03-01 --provider amp

Cost estimate: Free with Claude CLI (included with Claude subscription, but rate limited). Use --provider amp to avoid rate limits (~$0.50-2.00 per month, depends on message volume).

Step 2: Generate Chapter Titles

Generate evocative chapter titles for periods that have summaries but no title.

# Generate titles for all periods missing them
bun run summarize --generate-titles

# Filter by type and date range
bun run summarize --generate-titles --type month --start 2021-01-01 --end 2021-12-31

Cost estimate: ~$0.01-0.02 per title

Step 3: Describe Images

Uses Gemini to generate descriptions of all images in the Slack export. This enables semantic image search for the next step.

# Set your API keys
export GEMINI_API_KEY="your-api-key-here"
export SLACK_TOKEN="xoxb-your-slack-bot-token"  # Required to fetch images from Slack

# Describe all images (runs in parallel)
bun run describe-images

# Filter by date range
bun run describe-images --from 2021-01-01 --to 2021-12-31

# Limit number of images processed
bun run describe-images --limit 1000

# Retry only previously failed images
bun run describe-images --retry-failed

# Dry run to see what would be processed
bun run describe-images --dry-run

Cost estimate: ~$0.001 per image (Gemini Flash is very cheap). For 80k images, expect ~$80.

Step 4: Select Featured Images

Uses Claude/Amp to select the 5 best images for each period based on the summary content.

# Select images for all periods
bun run select-images

# Filter by date range
bun run select-images --from 2021-01-01 --to 2021-12-31

# Limit to specific number of periods
bun run select-images --limit 10

# Use an existing Amp thread for context
bun run select-images --from 2022-07-01 --to 2022-07-01 --set-thread T-xxxxx

Cost estimate: ~$0.10-0.30 per period

Importing Google Slides

Import Google Slides presentations to make their content searchable alongside Slack history.

Prerequisites

• Google OAuth access token - Get from OAuth Playground
  • Select scopes: presentations.readonly and drive.metadata.readonly

Step 1: Import Presentations

cd summarizer

# Set your access token
export GOOGLE_ACCESS_TOKEN="ya29.xxx..."

# Import a single presentation
bun run import-slides https://docs.google.com/presentation/d/1abc123/edit

# Import multiple presentations
bun run import-slides 1abc123 2def456 3ghi789

# Import from a file (one URL/ID per line)
bun run import-slides -f presentations.txt

# Import all presentations from a Google Drive folder
bun run import-slides --folder https://drive.google.com/drive/folders/1abc123

# Import from folder recursively (includes subfolders)
bun run import-slides --folder 1abc123 --recursive

# Preview without importing
bun run import-slides --dry-run https://docs.google.com/presentation/d/1abc123/edit

Step 2: Generate Slide Descriptions

Uses Gemini to analyze each slide image and write detailed descriptions that capture visual layout, diagrams, and meaning.

# Set your API key
export GEMINI_API_KEY="your-api-key-here"

# Describe all slides
bun run describe-slides

# Filter to specific presentation
bun run describe-slides --presentation 1abc123

# Limit number of slides
bun run describe-slides --limit 50

# Preview what would be processed
bun run describe-slides --dry-run

Cost estimate: ~$0.002 per slide (Gemini Flash, ~1KB output per slide)

Importing Google Docs

Import Google Docs (strategy memos, meeting notes, etc.) as markdown.

cd summarizer

# Set your access token
export GOOGLE_ACCESS_TOKEN="ya29.xxx..."

# Import a single document
bun run import-docs https://docs.google.com/document/d/1abc123/edit

# Import all documents from a folder
bun run import-docs --folder https://drive.google.com/drive/folders/1abc123

# Include subfolders
bun run import-docs --folder 1abc123 --recursive

# Preview without importing
bun run import-docs --dry-run --folder 1abc123

Documents are stored with both markdown and plain text content, plus word count.

Refining Summaries

After initial generation, summaries can be refined using Google Slides content and cross-summary editing.

Align Summaries with Presentations

Aligns existing summaries with Google Slides presentations (e.g., All Hands) to ensure company-wide priorities are reflected.

cd summarizer

# Align a single month
bun run align-summaries --start 2022-01-01

# Align a date range
bun run align-summaries --start 2022-01-01 --end 2022-12-31

# Preview changes without saving
bun run align-summaries --start 2022-01-01 --preview

# Show what would be processed
bun run align-summaries --start 2022-01-01 --dry-run

# Use Amp instead of Claude
bun run align-summaries --start 2022-01-01 --provider amp

Cost estimate: ~$0.20-0.50 per month (depends on number of slides)

Edit Summaries for Cohesion

Reviews multiple summaries together for narrative consistency, repetitive language, and factual errors.

cd summarizer

# Review all monthly summaries
bun run edit-summaries

# Filter by date range
bun run edit-summaries --start 2022-01-01 --end 2022-12-31

# Use Amp instead of Claude
bun run edit-summaries --provider amp

The editor outputs issues to fix but doesn't modify the database directly. Review the output in data/logs/editor-*.log and apply fixes manually or with scripts.

Cost estimate: ~$0.50-1.00 per review session (depends on number of summaries)

Step 5: Refresh Images (Optional)

If you need to update the image pool for periods without re-running image selection:

bun run summarize --refresh-images
bun run summarize --refresh-images --type month

Cost estimate: Free (no LLM calls, just database updates)

Cost Summary

Step	Per Unit	For 67 Months
Summaries	$0.50-2.00/month	~$70-130
Titles	$0.01-0.02/title	~$1-2
Describe Images	$0.001/image	~$80 (80k images)
Select Images	$0.10-0.30/period	~$10-20
Describe Slides	$0.002/slide	~$10-20
Align Summaries	$0.20-0.50/month	~$15-35
Edit Summaries	$0.50-1.00/session	~$5-10
Total		~$190-305

Adapting for Another Company

This project was built for Gather but can be adapted for any Slack workspace. All company-specific configuration is in a single file:

config/company.ts

Edit this file to configure:

• Company name and description (for AI context)
• Slack workspace subdomain (for message links)
• Image context (typical image types for your company)
• Title context (for chapter title generation)
• Example caption (for image selection prompts)
• App branding title

Deployment

See deploy/README.md for Kubernetes deployment instructions.