It’s output is really cool and I encourage you to try it and read it through!

Command: /insights

Description: “Generate a report analyzing your Claude Code sessions”

Output: An interactive HTML report saved to ~/.claude/usage-data/report.html

But what’s really happening under the hood? Let’s trace through the entire pipeline.

The Analysis Pipeline

The insights generation is a multi-stage process:

1. Collect all your session logs from ~/.claude/projects/
2. Filter out agent sub-sessions and internal operations
3. Extract metadata from each session (tokens, tools used, duration, etc.)
4. Run LLM analysis to extract “facets” (qualitative assessments) from session transcripts
5. Aggregate all the data across sessions
6. Generate insights using multiple specialized prompts
7. Render an interactive HTML report

The facets are cached in ~/.claude/usage-data/facets/ so subsequent runs are faster.

Stage 1: Session Filtering & Metadata Extraction

Before any LLM calls, Claude Code processes your session logs to extract structured metadata.

Sessions are filtered to exclude:

• Agent sub-sessions (files starting with agent-)
• Internal facet-extraction sessions
• Sessions with fewer than 2 user messages
• Sessions shorter than 1 minute

Metadata extracted per session:

• session_id - Unique identifier
• start_time - When the session began
• duration_minutes - How long the session lasted
• user_message_count - Number of user messages
• input_tokens / output_tokens - Token usage
• tool_counts - Which tools were used and how often
• languages - Programming languages detected from file extensions
• git_commits / git_pushes - Git activity
• user_interruptions - How often you interrupted Claude
• tool_errors - Tool failures and their categories
• lines_added / lines_removed / files_modified - Code changes
• uses_task_agent / uses_mcp / uses_web_search / uses_web_fetch - Feature usage
• first_prompt - Your initial message
• summary - Brief session summary

Stage 2: Transcript Summarization (For Long Sessions)

If a session transcript exceeds 30,000 characters, it’s chunked into 25,000-character segments and each chunk is summarized before facet extraction.

Transcript Summarization Prompt

Summarize this portion of a Claude Code session transcript. Focus on:
1. What the user asked for
2. What Claude did (tools used, files modified)
3. Any friction or issues
4. The outcome

Keep it concise - 3-5 sentences. Preserve specific details like file names,
error messages, and user feedback.

TRANSCRIPT CHUNK:

Stage 3: Facet Extraction

This is the core qualitative analysis. For each session (up to 50 new sessions per run), Claude analyzes the transcript to extract structured “facets” - qualitative assessments of what happened.

Model: Haiku (fast, cost-effective) Max output tokens: 4096

Facet Extraction Prompt

Analyze this Claude Code session and extract structured facets.

CRITICAL GUIDELINES:

1. **goal_categories**: Count ONLY what the USER explicitly asked for.
   - DO NOT count Claude's autonomous codebase exploration
   - DO NOT count work Claude decided to do on its own
   - ONLY count when user says "can you...", "please...", "I need...", "let's..."

2. **user_satisfaction_counts**: Base ONLY on explicit user signals.
   - "Yay!", "great!", "perfect!" → happy
   - "thanks", "looks good", "that works" → satisfied
   - "ok, now let's..." (continuing without complaint) → likely_satisfied
   - "that's not right", "try again" → dissatisfied
   - "this is broken", "I give up" → frustrated

3. **friction_counts**: Be specific about what went wrong.
   - misunderstood_request: Claude interpreted incorrectly
   - wrong_approach: Right goal, wrong solution method
   - buggy_code: Code didn't work correctly
   - user_rejected_action: User said no/stop to a tool call
   - excessive_changes: Over-engineered or changed too much

4. If very short or just warmup, use warmup_minimal for goal_category

SESSION:
<session transcript is inserted here>

RESPOND WITH ONLY A VALID JSON OBJECT matching this schema:
{
  "underlying_goal": "What the user fundamentally wanted to achieve",
  "goal_categories": {"category_name": count, ...},
  "outcome": "fully_achieved | mostly_achieved | 
              partially_achieved | not_achieved | 
              unclear_from_transcript",
  "user_satisfaction_counts": {"level": count, ...},
  "claude_helpfulness": "unhelpful | slightly_helpful | moderately_helpful | very_helpful | essential",
  "session_type": "single_task | multi_task | iterative_refinement | exploration | quick_question",
  "friction_counts": {"friction_type": count, ...},
  "friction_detail": "One sentence describing friction or empty",
  "primary_success": "none | fast_accurate_search | correct_code_edits | good_explanations | proactive_help | multi_file_changes | good_debugging",
  "brief_summary": "One sentence: what user wanted and whether they got it"
}

Goal Categories

Satisfaction Levels:

frustrated → dissatisfied → likely_satisfied → satisfied → happy → unsure

Outcome Categories:

not_achieved → partially_achieved → mostly_achieved → fully_achieved → unclear_from_transcript

Friction Categories

Claude Helpfulness Levels:

unhelpful → slightly_helpful → moderately_helpful → very_helpful → essential

Session Types

Primary Success Categories

Stage 4: Aggregated Analysis

Once all session data and facets are collected, they’re aggregated and processed through multiple specialized analysis prompts.

Model: Haiku Max output tokens: 8192 per prompt

Data Passed to Analysis Prompts

Each analysis prompt receives aggregated statistics:

{
  sessions: <total sessions>,
  analyzed: <sessions with facets>,
  date_range: { start, end },
  messages: <total messages>,
  hours: <total duration in hours>,
  commits: <git commits>,
  top_tools: [top 8 tools by usage],
  top_goals: [top 8 goal categories],
  outcomes: { outcome distribution },
  satisfaction: { satisfaction distribution },
  friction: { friction type counts },
  success: { success category counts },
  languages: { language usage counts }
}

Plus text summaries:

• SESSION SUMMARIES: Up to 50 brief summaries
• FRICTION DETAILS: Up to 20 friction details from facets
• USER INSTRUCTIONS TO CLAUDE: Up to 15 repeated instructions users gave Claude

4.1 Project Areas Analysis

Analyze this Claude Code usage data and identify project areas.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "areas": [
    {
      "name": "Area name",
      "session_count": N,
      "description": "2-3 sentences about what was worked on and how Claude Code was used."
    }
  ]
}

Include 4-5 areas. Skip internal CC operations.

4.2 Interaction Style Analysis

Analyze this Claude Code usage data and describe the user's interaction style.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "narrative": "2-3 paragraphs analyzing HOW the user interacts with Claude Code.
               Use second person 'you'. Describe patterns: iterate quickly vs
               detailed upfront specs? Interrupt often or let Claude run?
               Include specific examples. Use **bold** for key insights.",
  "key_pattern": "One sentence summary of most distinctive interaction style"
}

4.3 What Works Well

Analyze this Claude Code usage data and identify what's working well for this user.
Use second person ("you").

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence of context",
  "impressive_workflows": [
    {
      "title": "Short title (3-6 words)",
      "description": "2-3 sentences describing the impressive workflow or approach.
                      Use 'you' not 'the user'."
    }
  ]
}

Include 3 impressive workflows.

4.4 Friction Analysis

Analyze this Claude Code usage data and identify friction points for this user.
Use second person ("you").

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence summarizing friction patterns",
  "categories": [
    {
      "category": "Concrete category name",
      "description": "1-2 sentences explaining this category and what could be
                      done differently. Use 'you' not 'the user'.",
      "examples": ["Specific example with consequence", "Another example"]
    }
  ]
}

Include 3 friction categories with 2 examples each.

4.5 Suggestions & Improvements

This is the longest prompt, providing actionable recommendations:

Analyze this Claude Code usage data and suggest improvements.

## CC FEATURES REFERENCE (pick from these for features_to_try):

1. **MCP Servers**: Connect Claude to external tools, databases, and APIs via
   Model Context Protocol.
   - How to use: Run `claude mcp add <server-name> -- <command>`
   - Good for: database queries, Slack integration, GitHub issue lookup,
     connecting to internal APIs

2. **Custom Skills**: Reusable prompts you define as markdown files that run
   with a single /command.
   - How to use: Create `.claude/skills/commit/SKILL.md` with instructions.
     Then type `/commit` to run it.
   - Good for: repetitive workflows - /commit, /review, /test, /deploy, /pr,
     or complex multi-step workflows

3. **Hooks**: Shell commands that auto-run at specific lifecycle events.
   - How to use: Add to `.claude/settings.json` under "hooks" key.
   - Good for: auto-formatting code, running type checks, enforcing conventions

4. **Headless Mode**: Run Claude non-interactively from scripts and CI/CD.
   - How to use: `claude -p "fix lint errors" --allowedTools "Edit,Read,Bash"`
   - Good for: CI/CD integration, batch code fixes, automated reviews

5. **Task Agents**: Claude spawns focused sub-agents for complex exploration
   or parallel work.
   - How to use: Claude auto-invokes when helpful, or ask "use an agent to explore X"
   - Good for: codebase exploration, understanding complex systems

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "claude_md_additions": [
    {
      "addition": "A specific line or block to add to CLAUDE.md based on workflow
                   patterns. E.g., 'Always run tests after modifying auth-related files'",
      "why": "1 sentence explaining why this would help based on actual sessions",
      "prompt_scaffold": "Instructions for where to add this in CLAUDE.md.
                          E.g., 'Add under ## Testing section'"
    }
  ],
  "features_to_try": [
    {
      "feature": "Feature name from CC FEATURES REFERENCE above",
      "one_liner": "What it does",
      "why_for_you": "Why this would help YOU based on your sessions",
      "example_code": "Actual command or config to copy"
    }
  ],
  "usage_patterns": [
    {
      "title": "Short title",
      "suggestion": "1-2 sentence summary",
      "detail": "3-4 sentences explaining how this applies to YOUR work",
      "copyable_prompt": "A specific prompt to copy and try"
    }
  ]
}

IMPORTANT for claude_md_additions: PRIORITIZE instructions that appear MULTIPLE TIMES
in the user data. If user told Claude the same thing in 2+ sessions (e.g.,
'always run tests', 'use TypeScript'), that's a PRIME candidate - they shouldn't
have to repeat themselves.

IMPORTANT for features_to_try: Pick 2-3 from the CC FEATURES REFERENCE above.
Include 2-3 items for each category.

4.6 On The Horizon (Future Opportunities)

Analyze this Claude Code usage data and identify future opportunities.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence about evolving AI-assisted development",
  "opportunities": [
    {
      "title": "Short title (4-8 words)",
      "whats_possible": "2-3 ambitious sentences about autonomous workflows",
      "how_to_try": "1-2 sentences mentioning relevant tooling",
      "copyable_prompt": "Detailed prompt to try"
    }
  ]
}

Include 3 opportunities. Think BIG - autonomous workflows, parallel agents,
iterating against tests.

4.7 Fun Ending (Memorable Moment)

Analyze this Claude Code usage data and find a memorable moment.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "headline": "A memorable QUALITATIVE moment from the transcripts - not a statistic.
               Something human, funny, or surprising.",
  "detail": "Brief context about when/where this happened"
}

Find something genuinely interesting or amusing from the session summaries.

Stage 5: At a Glance Summary

The final LLM call generates an executive summary that ties everything together. This prompt receives all the previously generated insights as context.

At a Glance Prompt

You're writing an "At a Glance" summary for a Claude Code usage insights report
for Claude Code users. The goal is to help them understand their usage and
improve how they can use Claude better, especially as models improve.

Use this 4-part structure:

1. **What's working** - What is the user's unique style of interacting with Claude
   and what are some impactful things they've done? You can include one or two
   details, but keep it high level since things might not be fresh in the user's
   memory. Don't be fluffy or overly complimentary. Also, don't focus on the
   tool calls they use.

2. **What's hindering you** - Split into (a) Claude's fault (misunderstandings,
   wrong approaches, bugs) and (b) user-side friction (not providing enough
   context, environment issues -- ideally more general than just one project).
   Be honest but constructive.

3. **Quick wins to try** - Specific Claude Code features they could try from the
   examples below, or a workflow technique if you think it's really compelling.
   (Avoid stuff like "Ask Claude to confirm before taking actions" or "Type out
   more context up front" which are less compelling.)

4. **Ambitious workflows for better models** - As we move to much more capable
   models over the next 3-6 months, what should they prepare for? What workflows
   that seem impossible now will become possible? Draw from the appropriate
   section below.

Keep each section to 2-3 not-too-long sentences. Don't overwhelm the user.
Don't mention specific numerical stats or underlined_categories from the
session data below. Use a coaching tone.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "whats_working": "(refer to instructions above)",
  "whats_hindering": "(refer to instructions above)",
  "quick_wins": "(refer to instructions above)",
  "ambitious_workflows": "(refer to instructions above)"
}

SESSION DATA:
<aggregated statistics JSON>

## Project Areas (what user works on)
<project_areas results>

## Big Wins (impressive accomplishments)
<what_works results>

## Friction Categories (where things go wrong)
<friction_analysis results>

## Features to Try
<suggestions.features_to_try results>

## Usage Patterns to Adopt
<suggestions.usage_patterns results>

## On the Horizon (ambitious workflows for better models)
<on_the_horizon results>

Stage 6: Report Generation

All the collected data and LLM-generated insights are rendered into an interactive HTML report.

Statistics Dashboard:

• Total sessions, messages, duration, tokens
• Git commits and pushes
• Active days and streaks
• Peak activity hours

Visualizations:

• Daily activity charts
• Tool usage distribution
• Language breakdown
• Satisfaction distribution
• Outcome tracking

Narrative Sections:

• Project areas with descriptions
• Interaction style analysis
• What’s working well (impressive workflows)
• Friction analysis with specific examples
• CLAUDE.md additions to try
• Features to explore
• On the horizon opportunities
• Fun memorable moment

Pipeline Pseudocode

Here’s how the stages connect:

function generateInsights():
    // Stage 1: Load and filter sessions
    sessions = loadSessionLogs("~/.claude/projects/")
    sessions = sessions.filter(s =>
        !isAgentSession(s) &&
        !isInternalSession(s) &&
        s.userMessageCount >= 2 &&
        s.durationMinutes >= 1
    )

    // Extract metadata from each session
    metadata = sessions.map(extractMetadata)

    // Stage 2 & 3: Extract facets (with caching)
    facets = {}
    for session in sessions:
        cached = loadCachedFacet(session.id)
        if cached:
            facets[session.id] = cached
        else:
            transcript = session.transcript
            if transcript.length > 30000:
                transcript = summarizeInChunks(transcript)

            facets[session.id] = callLLM(FACET_EXTRACTION_PROMPT + transcript)
            saveFacetToCache(session.id, facets[session.id])

    // Stage 4: Aggregate and analyze
    aggregated = aggregateAllData(metadata, facets)

    insights = {}
    insights.project_areas = callLLM(PROJECT_AREAS_PROMPT, aggregated)
    insights.interaction_style = callLLM(INTERACTION_STYLE_PROMPT, aggregated)
    insights.what_works = callLLM(WHAT_WORKS_PROMPT, aggregated)
    insights.friction = callLLM(FRICTION_PROMPT, aggregated)
    insights.suggestions = callLLM(SUGGESTIONS_PROMPT, aggregated)
    insights.on_the_horizon = callLLM(ON_THE_HORIZON_PROMPT, aggregated)
    insights.fun_ending = callLLM(FUN_ENDING_PROMPT, aggregated)

    // Stage 5: Generate executive summary
    insights.at_a_glance = callLLM(AT_A_GLANCE_PROMPT, aggregated + insights)

    // Stage 6: Render HTML report
    html = renderReport(aggregated, insights)
    saveFile("~/.claude/usage-data/report.html", html)

    return insights

Data Storage

Facets are cached per-session, so running /insights multiple times only analyzes new sessions.

Technical Details

Privacy Considerations

All analysis happens locally using the Anthropic API. Your session data stays on your machine - the HTML report is generated locally and can be shared at your discretion.

The facet extraction focuses on patterns in your interactions, not the content of your code:

• What types of tasks you ask for
• How you respond to Claude’s output
• Where friction occurs in the workflow
• Which tools and features you use

Tips for Better Insights

1. Use Claude Code regularly - More sessions = richer analysis
2. Give feedback - Say “thanks” or “that’s not right” so satisfaction can be tracked
3. Don’t filter yourself - Natural usage patterns reveal the most useful insights
4. Run periodically - Check in monthly to see how your patterns evolve

We've taken action to prevent third-party clients from spoofing the Claude Code agent harness to use consumer subscriptions. Consumer subscriptions and their benefits should only be used in the Anthropic experiences they support (Claude Code CLI, Claude Code web, and via sessionKey in the Agent SDK). Third-party apps can use the API.

— Alex Albert (@trq212) January 12, 2025

From what I can gather, consumer subscriptions work with official Anthropic tools, not third-party applications. If you want third-party integrations, you need the API.

Official Tools

Claude Desktop and Mobile Apps

The consumer applications (desktop and mobile) are the most straightforward way to use your Claude subscription. Available at claude.com/download, these apps give you direct access to Claude for conversation, file uploads, and Projects.

Claude Code CLI

The official command-line interface for Claude Code is fully supported with Claude subscriptions. This is the tool Anthropic built and maintains specifically for developers who want to use Claude in their development workflow.

You get the full power of Claude integrated into your terminal, with access to your entire codebase, the ability to execute commands, read and write files, and use all the specialized agents that come with Claude Code.

Claude Code on the Web

The web version of Claude Code (accessible through your browser at claude.ai/code) provides the same capabilities as the CLI but through a browser interface. Upload your project files, or point it at a repository, and you can work with Claude on your codebase directly.

Claude Agent SDK

Want to experiment with building custom agents? The Claude Agent SDK lets you develop and test specialized agents powered by your Claude subscription for personal development work.

The SDK is available in both Python and TypeScript, with documentation here.

This is for personal experiments and development. For production deployments of agents, use the API instead of your subscription.

Claude Code GitHub Action

You can use your Claude subscription to run automated agents in GitHub Actions. The Claude Code Action lets you set up workflows that leverage Claude for code review, documentation generation, or automated testing analysis. Documentation is here.

Any other uses of Claude would require the use of API keys.

Summary

Your Claude subscription gives you:

• Claude desktop and mobile apps for general use
• Claude Code CLI for terminal-based development
• Claude Code on the web for browser-based work
• The ability to build custom agents through the official SDK (for personal development)
• Claude Code GitHub Action for CI/CD integration

Let me know if you have any corrections.

Fizzy takes that seriously. When 37signals released Fizzy with its full git history available, they didn’t just open-source the code — they shipped a complete API and webhook system too. The doors were wide open baby!

So I dove in — reading the source, building tools, and sharing what I found. Every time curiosity kicked in, there was a direct path from “I wonder if…” to something I could actually try and execute. This post is a catch-all for my very bubbly month of December.

Writing

Fizzy Webhooks: What You Need to Know — I set up a local webhook receiver to capture and document every event type Fizzy sends. The post covers the payload structures, signature verification, and ideas for what you could build on top of the webhook system.

The Making of Fizzy, Told by Git — I prompted Claude Code to analyze the entire git history and write a documentary about the development.

Vanilla CSS is all you need — Diving into the no-build CSS architecture across Campfire, Writebook, and Fizzy.

Fizzy Design Evolution: A Flipbook from Git — I went through each day of commits, got the application to a bootable state, seeded the database, and took a screenshot. Then I stitched those screenshots into a flipbook video with a soundtrack made from Fizzy’s own audio files.

Fizzy’s Pull Requests: Who Built What and How — An analysis of who owned which domains in the Fizzy codebase. The post maps contributors to their expertise areas and curates learning paths through the PRs for topics like Turbo/Hotwire, caching, AI integration, multi-tenancy, and webhooks.

Code

The open API invited experimentation. I spotted gaps that would make integration easier for other developers, so I filled them:

fizzy-api-client — Ruby client for the Fizzy API.

fizzy-client-python — Python client for the Fizzy API.

fizzy-cli — Command-line interface for the Fizzy API, built first in Ruby and then migrated to Go for portability.

fizzy-skill — An AI agent skill for interacting with Fizzy.

n8n-nodes-fizzy — An n8n community node that brings Fizzy into your automation workflows. Create cards, manage assignments, and react to real-time events through webhook triggers.

Migration tools — I built these to make it easier to try Fizzy without starting from scratch. Migrating your existing issues and boards gives you an immediate sense of how it could work for you, without having to manually create test cards. You can see your real data running in Fizzy from day one, which I think makes it easier to evaluate and decide if its useful for you.

• linear2fizzy — Migrate Linear issues
• jira2fizzy — Migrate JIRA issues
• asana2fizzy — Migrate Asana tasks
• gh2fizzy — Migrate GitHub Issues
• prd2fizzy — Convert PRDs to Fizzy cards

Contributions to Fizzy

I also contributed a few small fixes back to the main repository:

• #2114 — Remove unused install.svg and its CSS class
• #2111 — Remove unpaired view-transition-name
• #2095 — Fix typo: minues → minutes
• #2094 — Fix duplicate word: use use → use
• #2093 — Add QrCodesController test
• #2088 — Fix view-transition-name typo in public card show

O’Saasy Directory

Fizzy is released under the O’Saasy License, which is similar in spirit to MIT but includes a restriction on offering the software as a competing hosted or SaaS product. You can modify and self-host it, but you can’t repackage it and sell it as your own hosted service.

I built O’Saasy Directory to make it easy to find applications released under this license.

Beyond Fizzy, the directory includes other submitted projects where the source is available to read and modify. If you have built something under the O’Saasy License, visit the submission page to add yours.

CarbonationLabs

Having built the Fizzy CLI and fizzy-api-client Rubygem, I saw some fun opportunities to build little lab experiments to show how Fizzy could be integrated with - both to power up some functionality that isn’t there yet, but also creating boards in some interesting ways (eg Movie Quiz). I got the idea for this on a flight to Australia with no internet. Just a pad of paper and a pen. I should probably do that more often as a bunch of ideas for all sorts of products came out.

CarbonationLabs is not a product per se. It’s an open source Rails application designed to be run locally where you can interact with the hosted or self-hosted versions of Fizzy. If anything I hope it inspires creation of little problem solving workflows for Fizzy that wouldn’t be built into the main product (the problem is too niche). The API and webhook system is really flexible and most of your bespoke problems could be solved with some creative thinking.

Introducing Carbonation Labs - fun ways to add experiments to and extend Fizzy (repo link and demo videos below)🧵

— Rob Zolkos (@robzolkos) December 27, 2025

carbonation.dev

I built carbonation.dev to bring together all the tools, libraries, and integrations that I and others in the community have created for Fizzy. It’s a directory covering API clients (Ruby, Python, JavaScript), CLI tools with packages for macOS, Arch Linux, Debian, Fedora, and Windows, integrations for Claude Code and other AI agents, n8n, Raycast, Telegram, and MCP servers, plus migration tools for GitHub, Linear, Asana, and Jira.

If you’ve built something for Fizzy, I’d love to feature it. You can submit a pull request to add your tool to the directory.

What I Learned

Building the Fizzy CLI pushed me into some new territory. I created an AUR package for Arch Linux users, set up a Homebrew tap for macOS, published my first Python package to PyPI, and made an n8n plugin — all firsts for me. While I already knew Go, rewriting the CLI in it was a fun exercise, and building TUIs for the setup and skill commands introduced me to terminal UI libraries I hadn’t used before. Gosh it was fun!

If you want to get better at Rails, Fizzy is a great place to study real-world code. And in my view if you want to work at 37signals as a Rails programmer, digging into Fizzy — along with Campfire and Writebook — is a solid way to learn how they approach Rails architecture and design decisions. Submitting PRs is also a good way to contribute back while learning — just be respectful of the contribution policy. The review discussions give you a window into how to reason about problems, spot opportunities, and make trade-offs.

This month pushed parts of my creative thinking that weren’t gone, but definitely weren’t being stressed. Like any muscle, use it or lose it. The direction of what to explore came from my own curiosity and a habit of poking around under the hood, and AI helped me move a lot faster once I knew where I wanted to go. Most of this information already exists somewhere — Google, Stack Overflow, documentation — but having AI right there alongside me as a partner was thrilling.

All of this was made possible because a team left the doors open. No one asked me to step inside; I decided to invest the time and do the work to see what I could build, learn and share. I do this at work too—when I can—looking for opportunities I can shape, experiment with, and get genuinely excited about. Most importantly I had fun and I hope you enjoyed following along.

Below you will read which 37signals team members owned which domains in this project, and which PRs best demonstrate their craft. If you’re new to the codebase (or want to level up in specific areas), I will point you to the PRs worth studying. Each section highlights an engineer’s domain knowledge and the code reviews that showcase their thinking.

Why Read Pull Requests?

Reading the code shows the outcome. Pull requests show the decisions.

I love reading PRs because they reveal the reasoning behind the work, the options considered and the tradeoffs made. Review comments often become real lessons as people question choices, suggest alternatives, and offer encouragement.

These reviews can create quick, informal mentorship where one person spots a cleaner abstraction and another catches an edge case before it slips through.

Follow a codebase through its PRs and you can see the product being built in real time as early spikes set patterns, refactors clear debt, and new features rise on earlier work.

Want to dive into a specific topic? Jump to the Learning Paths for curated PR sequences on AI/LLM integration, multi-tenancy with SQLite, Turbo/Hotwire, and more.

So I got to work: I went through each day of commits in the Fizzy repository, got the application to a bootable state, seeded the database, and took a screenshot. Then I stitched those screenshots together into a flipbook-style video.

Here’s the final result - I hope you enjoy it! Read on below for details about the process and the backing music.

The Process

The Fizzy repository has 8,152 commits spanning from June 2024 to November 2025. I extracted the git SHA of the last commit from each day, excluding dependabot commits - a good proxy for the state of the app at the end of each work day.

With that list I then copied the Fizzy source into dated folders and checked out the corresponding SHA for each. I then wrote and ran a sanity check script to ensure the right Ruby versions were installed, that bundle install worked, and that database migrations and seeds completed successfully.

Once each folder was ready, the screenshot process began:

1. Boot the application
2. Use Playwright to log in and navigate to the correct page
3. Capture the screenshot

I worked in batches of 10 checkpoints at a time to verify I was capturing the right page, since routes changed throughout the project’s history.

Not every checkpoint was bootable. Schema migrations sometimes broke older seeds. Gems changed. Dependencies shifted—including private gems I didn’t have access to. Some checkpoints required manual fixes to get the application running. But persistence paid off - I captured all the screenshots to show the visual journey from “splats on a windshield” (the original playful blob metaphor) to the polished kanban board that shipped.

The Music

As I watched the completed flipbook, it lacked any backing music—kinda boring! I remembered Jason Fried mentioning on the Fizzy livestream demo that if you hold Shift while dragging a card to another column, Fizzy plays a little sound—a different one per column.

So I did what anyone making a flipbook out of git history screenshots in 2025 would do: I asked Claude to stitch those original sound files from the repo into a soundtrack. Because what else would you use to score a Fizzy flipbook besides Fizzy’s own sound files?

From there, Claude ensured ffmpeg was installed and got to work. We iterated a few times - “vibe music produced” - until it sounded right. A really fun way to bring some life to what would have otherwise been a silent flipbook.

What Stands Out

Watching the design evolve frame by frame reveals things the commit history can only hint at:

Epicenter design. You can see epicenter design in action—a philosophy that’s been at the core of 37signals’ process for decades. The team started with the most essential elements (the grouping of bubbles/cards) and built outward from there. Navigation, chrome, and secondary features came later. The flipbook shows this progression clearly: core functionality first, polish second.

The color exploration. Early versions experimented with bold, vibrant colors. The palette refined over time into something more subdued and professional while retaining the signature fun style 37signals applications are known for.

Layout density. The interface started sparse and grew more information-dense as features accumulated, then simplified again in the later months.

The bubble-to-card transition. You can see the playful, organic blob shapes gradually give way to more structured rectangular cards. The whimsy of the early windshield metaphor fades into the pragmatism of a task management tool.

Typography and spacing. Subtle but constant. Every few frames you notice tighter line heights, adjusted padding, refined font weights. The polish accumulated through hundreds of small commits.

Animation. You can’t see the subtle hover animations in a flipbook of static screenshots, but the team experimented with movement and texture throughout development. Here are a few examples:

This kind of archaeology is only possible because 37signals kept the full git history intact. Most companies would have squashed or rebased this history into oblivion before open-sourcing. The fact that they didn’t is a gift to anyone curious about how software really gets made.

Let me know if you try something similar with another codebase. The process is time-consuming but oddly satisfying.

The post stuck with me. Over the past year and a half, 37signals has released two more products (Writebook and Fizzy) built on the same nobuild philosophy. I wanted to know if these patterns held up. Had they evolved?

I cracked open the source code for Campfire, Writebook, and Fizzy and traced the evolution of their CSS architecture. What started as curiosity became genuine surprise. These are not just consistent patterns. They are improving patterns. Each release builds on the last, adopting progressively more modern CSS features while maintaining the same nobuild philosophy.

These are not hobby projects. Campfire is a real-time chat application. Writebook is a publishing platform. Fizzy is a full-featured project management tool with kanban boards, drag-and-drop, and complex state management. Combined, they represent nearly 14,000 lines of CSS across 105 files.

Not a single line touches a build tool.

The Tailwind Question

Let me be clear: there is nothing wrong with Tailwind. It is a fantastic tool that helps developers ship products faster. The utility-first approach is pragmatic, especially for teams that struggle with CSS architecture decisions.

But somewhere along the way, utility-first became the only answer. CSS has evolved dramatically. The language that once required preprocessors for variables and nesting now has:

• Native custom properties (variables)
• Native nesting
• Container queries
• The :has() selector (finally, a parent selector)
• CSS Layers for managing specificity
• color-mix() for dynamic color manipulation
• clamp(), min(), max() for responsive sizing without media queries

37signals looked at this landscape and made a bet: modern CSS is powerful enough. No build step required.

Three products later, that bet is paying off.

The Architecture: Embarrassingly Simple

Open any of these three codebases and you find the same flat structure:

app/assets/stylesheets/
├── _reset.css
├── base.css
├── colors.css
├── utilities.css
├── buttons.css
├── inputs.css
├── [component].css
└── ...

That is it. No subdirectories. No partials. No complex import trees. One file per concept, named exactly what it does.

Zero configuration. Zero build time. Zero waiting.

I would love to see something like this ship with new Rails applications. A simple starting structure with _reset.css, base.css, colors.css, and utilities.css already in place. I suspect many developers reach for Tailwind not because they prefer utility classes, but because vanilla CSS offers no starting point. No buckets. No conventions. Maybe CSS needs its own omakase.

The Color System: Consistent Foundation, Evolving Capabilities

Jason’s original post explained OKLCH well. It is the perceptually uniform color space all three apps use. The short version: unlike RGB or HSL, OKLCH’s lightness value actually corresponds to perceived brightness. A 50% lightness blue looks as bright as a 50% lightness yellow.

What is worth noting is how this foundation remains identical across all three apps:

:root {
  /* Raw LCH values: Lightness, Chroma, Hue */
  --lch-blue: 54% 0.15 255;
  --lch-red: 51% 0.2 31;
  --lch-green: 65% 0.23 142;

  /* Semantic colors built on primitives */
  --color-link: oklch(var(--lch-blue));
  --color-negative: oklch(var(--lch-red));
  --color-positive: oklch(var(--lch-green));
}

Dark mode becomes trivial:

@media (prefers-color-scheme: dark) {
  :root {
    --lch-blue: 72% 0.16 248;   /* Lighter, slightly desaturated */
    --lch-red: 74% 0.18 29;
    --lch-green: 75% 0.20 145;
  }
}

Every color that references these primitives automatically updates. No duplication. No separate dark theme file. One media query, and the entire application transforms.

Fizzy takes this further with color-mix():

.card {
  --card-color: oklch(var(--lch-blue-dark));

  /* Derive an entire color palette from one variable */
  --card-bg: color-mix(in srgb, var(--card-color) 4%, var(--color-canvas));
  --card-text: color-mix(in srgb, var(--card-color) 30%, var(--color-ink));
  --card-border: color-mix(in srgb, var(--card-color) 33%, transparent);
}

One color in, four harmonious colors out. Change the card color via JavaScript (element.style.setProperty('--card-color', '...')), and the entire card theme updates automatically. No class swapping. No style recalculation. Just CSS doing what CSS does best.

The Spacing System: Characters, Not Pixels

Here is a pattern I did not expect: all three applications use ch units for horizontal spacing.

:root {
  --inline-space: 1ch;      /* Horizontal: one character width */
  --block-space: 1rem;      /* Vertical: one root em */
}

.component {
  padding-inline: var(--inline-space);
  margin-block: var(--block-space);
}

Why characters? Because spacing should relate to content. A 1ch gap between words feels natural because it is literally the width of a character. As font size scales, spacing scales proportionally.

This also makes their responsive breakpoints unexpectedly elegant:

@media (min-width: 100ch) {
  /* Desktop: content is wide enough for sidebar */
}

Instead of asking “is this a tablet?”, they are asking “is there room for 100 characters of content?” It is semantic. It is content-driven. It works.

Utility Classes: Yes, They Still Exist

Let me address the elephant in the room. These applications absolutely use utility classes:

/* From utilities.css */
.flex { display: flex; }
.gap { gap: var(--inline-space); }
.pad { padding: var(--block-space) var(--inline-space); }
.txt-large { font-size: var(--text-large); }
.hide { display: none; }

The difference? These utilities are additive, not foundational. The core styling lives in semantic component classes. Utilities handle the exceptions: the one-off layout adjustment, the conditional visibility toggle.

Compare to a typical Tailwind component:

<!-- Tailwind approach -->
<button class="inline-flex items-center gap-2 px-4 py-2 rounded-full
               border border-gray-300 bg-white text-gray-900
               hover:bg-gray-50 focus:ring-2 focus:ring-blue-500">
  Save
</button>

And the 37signals equivalent:

<!-- Semantic approach -->
<button class="btn">Save</button>

.btn {
  --btn-padding: 0.5em 1.1em;
  --btn-border-radius: 2em;

  display: inline-flex;
  align-items: center;
  gap: 0.5em;
  padding: var(--btn-padding);
  border-radius: var(--btn-border-radius);
  border: 1px solid var(--color-border);
  background: var(--btn-background, var(--color-canvas));
  color: var(--btn-color, var(--color-ink));
  transition: filter 100ms ease;
}

.btn:hover {
  filter: brightness(0.95);
}

.btn--negative {
  --btn-background: var(--color-negative);
  --btn-color: white;
}

Yes, it is more CSS. But consider what you gain:

1. HTML stays readable. class="btn btn--negative" tells you what something is, not how it looks.
2. Changes cascade. Update --btn-padding once, every button updates.
3. Variants compose. Add .btn--circle without redefining every property.
4. Media queries live with components. Dark mode, hover states, and responsive behavior are co-located with the component they affect.

The :has() Revolution

If there is one CSS feature that changes everything, it is :has(). For decades, you needed JavaScript to style parents based on children. No more.

Writebook uses it for a sidebar toggle with no JavaScript:

/* When the hidden checkbox is checked, show the sidebar */
:has(#sidebar-toggle:checked) #sidebar {
  margin-inline-start: 0;
}

Fizzy uses it for kanban column layouts:

.card-columns {
  grid-template-columns: 1fr var(--column-width) 1fr;
}

/* When any column is expanded, adjust the grid */
.card-columns:has(.cards:not(.is-collapsed)) {
  grid-template-columns: auto var(--column-width) auto;
}

Campfire uses it for intelligent button styling:

/* Circle buttons when containing only icon + screen reader text */
.btn:where(:has(.for-screen-reader):has(img)) {
  --btn-border-radius: 50%;
  aspect-ratio: 1;
}

/* Highlight when internal checkbox is checked */
.btn:has(input:checked) {
  --btn-background: var(--color-ink);
  --btn-color: var(--color-ink-reversed);
}

This is CSS doing what you used to need JavaScript for. State management. Conditional rendering. Parent selection. All declarative. All in stylesheets.

Progression

What fascinated me most was watching the architecture evolve across releases.

Campfire (first release) established the foundation:

• OKLCH colors
• Custom properties for everything
• Character-based spacing
• Flat file organization
• View Transitions API for smooth page changes

Writebook (second release) added modern capabilities:

• Container queries for component-level responsiveness
• @starting-style for entrance animations

Fizzy (third release) went all-in on modern CSS:

• CSS Layers (@layer) for managing specificity
• color-mix() for dynamic color derivation
• Complex :has() chains replacing JavaScript state

You can see a team learning, experimenting, and shipping progressively more sophisticated CSS with each product. By Fizzy, they are using features many developers do not even know exist.

/* Fizzy's layer architecture */
@layer reset, base, components, modules, utilities;

@layer components {
  .btn { /* Always lower specificity than utilities */ }
}

@layer utilities {
  .hide { /* Always wins over components */ }
}

CSS Layers solve the specificity wars that have plagued CSS since the beginning. It does not matter what order your files load. It does not matter how many classes you chain. Layers determine the winner, period.

The Loading Spinner

One technique appears in all three applications that deserves special attention. Their loading spinners use no images, no SVGs, no JavaScript. Just CSS masks.

Here is the actual implementation from Fizzy’s spinners.css:

@layer components {
  .spinner {
    position: relative;

    &::before {
      --mask: no-repeat radial-gradient(#000 68%, #0000 71%);
      --dot-size: 1.25em;

      -webkit-mask: var(--mask), var(--mask), var(--mask);
      -webkit-mask-size: 28% 45%;
      animation: submitting 1.3s infinite linear;
      aspect-ratio: 8/5;
      background: currentColor;
      content: "";
      inline-size: var(--dot-size);
      inset: 50% 0.25em;
      margin-block: calc((var(--dot-size) / 3) * -1);
      margin-inline: calc((var(--dot-size) / 2) * -1);
      position: absolute;
    }
  }
}

The keyframes live in a separate animation.css file:

@keyframes submitting {
  0%    { -webkit-mask-position: 0% 0%,   50% 0%,   100% 0% }
  12.5% { -webkit-mask-position: 0% 50%,  50% 0%,   100% 0% }
  25%   { -webkit-mask-position: 0% 100%, 50% 50%,  100% 0% }
  37.5% { -webkit-mask-position: 0% 100%, 50% 100%, 100% 50% }
  50%   { -webkit-mask-position: 0% 100%, 50% 100%, 100% 100% }
  62.5% { -webkit-mask-position: 0% 50%,  50% 100%, 100% 100% }
  75%   { -webkit-mask-position: 0% 0%,   50% 50%,  100% 100% }
  87.5% { -webkit-mask-position: 0% 0%,   50% 0%,   100% 50% }
  100%  { -webkit-mask-position: 0% 0%,   50% 0%,   100% 0% }
}

Three dots, bouncing in sequence:

The background: currentColor means it automatically inherits the text color. Works in any context, any theme, any color scheme. Zero additional assets. Pure CSS creativity.

A Better <mark>

The default browser <mark> element renders as a yellow highlighter. It works, but it is not particularly elegant. Fizzy takes a different approach for search result highlighting: drawing a hand-drawn circle around matched terms.

Here is the implementation from circled-text.css:

@layer components {
  .circled-text {
    --circled-color: oklch(var(--lch-blue-dark));
    --circled-padding: -0.5ch;

    background: none;
    color: var(--circled-color);
    position: relative;
    white-space: nowrap;

    span {
      opacity: 0.5;
      mix-blend-mode: multiply;

      @media (prefers-color-scheme: dark) {
        mix-blend-mode: screen;
      }
    }

    span::before,
    span::after {
      border: 2px solid var(--circled-color);
      content: "";
      inset: var(--circled-padding);
      position: absolute;
    }

    span::before {
      border-inline-end: none;
      border-radius: 100% 0 0 75% / 50% 0 0 50%;
      inset-block-start: calc(var(--circled-padding) / 2);
      inset-inline-end: 50%;
    }

    span::after {
      border-inline-start: none;
      border-radius: 0 100% 75% 0 / 0 50% 50% 0;
      inset-inline-start: 30%;
    }
  }
}

The HTML structure is <mark class="circled-text"><span></span>webhook</mark>. The empty span exists solely to provide two pseudo-elements (::before and ::after) that draw the left and right halves of the circle.

The technique uses asymmetric border-radius values to create an organic, hand-drawn appearance. The mix-blend-mode: multiply makes the circle semi-transparent against the background, switching to screen in dark mode for proper blending.

Search results for: webhook

No images. No SVGs. Just borders and border-radius creating the illusion of a hand-drawn circle.

Dialog Animations: The New Way

Fizzy and Writebook both animate HTML <dialog> elements. This was notoriously difficult before. The secret is @starting-style.

Here is the actual implementation from Fizzy’s dialog.css:

@layer components {
  :is(.dialog) {
    border: 0;
    opacity: 0;
    transform: scale(0.2);
    transform-origin: top center;
    transition: var(--dialog-duration) allow-discrete;
    transition-property: display, opacity, overlay, transform;

    &::backdrop {
      background-color: var(--color-black);
      opacity: 0;
      transform: scale(1);
      transition: var(--dialog-duration) allow-discrete;
      transition-property: display, opacity, overlay;
    }

    &[open] {
      opacity: 1;
      transform: scale(1);

      &::backdrop {
        opacity: 0.5;
      }
    }

    @starting-style {
      &[open] {
        opacity: 0;
        transform: scale(0.2);
      }

      &[open]::backdrop {
        opacity: 0;
      }
    }
  }
}

The --dialog-duration variable is defined globally as 150ms.

Open Dialog

The @starting-style rule defines where the animation starts from when an element appears. Combined with allow-discrete, you can now transition between display: none and display: block. The modal smoothly scales and fades in. The backdrop fades independently. No JavaScript animation libraries. No manually toggling classes. The browser handles it.

What This Means for You

I am not suggesting you abandon your build tools tomorrow. But I am suggesting you reconsider your assumptions.

You might not need Sass or PostCSS. Native CSS has variables, nesting, and color-mix(). The features that needed polyfills are now baseline across browsers.

You might not need Tailwind for every project. Especially if your team understands CSS well enough to build a small design system.

While the industry sprints toward increasingly complex toolchains, 37signals is walking calmly in the other direction. Is this approach right for everyone? No. Large teams with varying CSS skill levels might benefit from Tailwind’s guardrails. But for many projects, their approach is a reminder that simpler can be better.

Thanks to Jason Zimdars and the 37signals team for sharing their approach openly. All code examples in this post are taken from the Campfire, Writebook, and Fizzy source code. For Jason’s original deep-dive into Campfire’s CSS patterns, see Modern CSS Patterns and Techniques in Campfire. If you want to learn modern CSS, these three codebases are an exceptional classroom.

I cloned down the repository and prompted Claude Code:

“Can you go through the entire git history and write a documentary about the development of this application. What date the first commit was. Any major tweaks, changes and decisions and experiments. You can take multiple passes and use sub-agents to build up a picture. Make sure to cite commits for any interesting things. If there is anything dramatic then make sure to see if you can figure out decision making. Summarize at the end but the story should go into STORY.md”

It responded with:

“This is a fascinating task! Let me create a comprehensive investigation plan and use multiple agents to build up a complete picture of this project’s history.”

Here is the story of Fizzy - as interpreted by Claude - from the trail of git commits. Enjoy!

From “Splats on a Windshield” to Open Source Project Management

A chronicle of 18 months of development at Basecamp, told through 8,152 commits.

Prologue: The Numbers

• First Commit: June 21, 2024
• Total Commits: 8,152
• Contributors: 25+
• Lines of Code Changed: Hundreds of thousands
• Name Changes: 4 (Splat → Bubble → Card; Project → Bucket → Collection → Board)
• Features Removed: At least 4 major ones
• DHH Commits in April 2025 Alone: 323

Act I: Genesis — “New Rails App”

June 21, 2024: Day Zero

At 1:19 PM on a summer Friday, Kevin McConnell typed the words that would begin an 18-month journey:

commit 564a0f48aebfaa4766e97d2d06eaf9ec51bd4ec3
Author: Kevin McConnell
Date: 2024-06-21

    New Rails app

Within hours, the foundation was laid. The team moved with practiced efficiency:

• 1:23 PM — Gemfile updated (e16323c)
• 3:47 PM — Rubocop configured (b9cf8c5)
• 4:07 PM — Minimal authentication flow (c4fb1bd)
• 4:29 PM — CSS reset and base styles (b90caf5)
• 4:46 PM — Brakeman security scanning added (ecae4a3)

By end of day, the skeleton of a Rails application stood ready. But what would it become?

Act II: The Splat Era — A Bug on Your Windshield

July 23, 2024: The Core Concept Emerges

One month after inception, Jason Zimdars introduced the application’s first real identity:

commit 932a83197b74741612d03c7f8606e1b5adefe25a
Author: Jason Zimdars
Date: 2024-07-23

    Add Splat model, controller, and views

A “Splat” — the name evokes something chaotic, impactful, unexpected. Like a bug hitting your windshield on a summer drive. The original data model was simple:

create_table :splats do |t|
  t.string :title
  t.text :body
  t.string :color  # dodgerblue, limegreen, tomato, mediumorchid
  t.timestamps
end

The next day brought the visual metaphor that would define the early application:

commit c2916a42d58d066d09930496eab551f1f6d496e6
Author: Jason Zimdars
Date: 2024-07-24

    Render with Flexbox, add windshield background

The windshield was the canvas. Splats appeared on it like bugs on glass — colorful, slightly chaotic, each one a piece of information demanding attention.

July 24, 2024: Preparing for the Demo

The commits reveal urgency. Something important was coming:

commit e139b5a72b0248fc9abbeae1f5a283b0c135ddd2
Author: Jason Zimdars
Date: 2024-07-24

    Still demo values, but make them stable

commit 75e402bea619a0af2774ede864978ef1904f446c
Author: Jason Zimdars
Date: 2024-08-14

    Handful of tweaks before all-hands

The all-hands demo. Approximately one month after project inception, Fizzy (then still called “Splat”) was shown to the entire company. The pressure to polish was evident in the commit messages.

Act III: “Let’s Try Bubbles”

July 31, 2024: The First Pivot

Seven days after the windshield metaphor was established, Jason Zimdars typed four words that would reshape the application’s identity:

commit 845e4618a57a4d92234732d6daa8da5f903c05a8
Author: Jason Zimdars
Date: 2024-07-31

    Let's try bubbles

The chaotic “splat” gave way to something gentler — bubbles floating on a windshield, like soap suds catching light. The animation changed from aggressive splattering to gentle floating:

@keyframes float-up-left {
  0% { transform: translate(10px, 40px); opacity: 0.1; }
  100% { transform: translate(0, 0); opacity: 1; }
}

August 2, 2024: Organic Evolution

commit 88b99ad1eb074cae09c72f9637a9d98b65b7aeed
Author: Jason Zimdars
Date: 2024-08-02

    Try a more organic bubble style

Perfect circles gave way to hand-drawn blob shapes. The team was discovering what their product was through the act of building it.

August 19-22, 2024: The “Boost” Feature — Foreshadowing the Name

A new interaction pattern emerged:

commit 40dcf9883 - "Add boosts model"
commit f39b58040 - "Display number of boosts on a splat"
commit 73f7ddca3 - "Animate when boosting (puffing up)"

When users “boosted” a bubble, it would puff up and float away — like champagne fizz rising. The animation:

@keyframes bubble-up {
  0% { transform: translate(0, 0); }
  50% { transform: translate(0, -4em); opacity: 0.66; }
  100% { transform: translate(0, -8em); opacity: 0; }
}

The metaphor was crystallizing. Bubbles. Fizzing. Effervescence. The name would come soon.

Act IV: Finding the Name

September 4, 2024: The Great Renaming

In a single day, the application found its final name through two commits:

commit 5aae70298 (September 4, 2024)
Author: Unknown

    Rename Splat to Bubble

42 files changed. The model, controllers, views, tests — everything touched.

Hours later:

commit e0763d4d4 (September 4, 2024)

    Splat -> Fizzy

Fizzy. The name captured everything: the bubbles, the effervescence, the playful energy of the interface. Visual design had driven product naming — the team discovered what they were building through the act of building it.

Act V: The Architecture Takes Shape

September 2024: Introducing Hierarchy

The flat list of bubbles needed structure:

commit c09a02fa9 (September 16, 2024)

    Introduce projects and accesses

commit 355e144dd (September 18, 2024)

    Nest bubbles et al under projects

But “Projects” didn’t feel right. Eight days later:

commit 4e579e5a3 (September 24, 2024)

    Rename Project to Bucket

Then “Bucket” became “Collection.” Eventually, “Collection” would become “Board.”

The terminology dance — Projects → Buckets → Collections → Boards — reveals a team searching for the right mental model. They ultimately landed on the familiar “Board” metaphor, aligning with tools like Trello and Linear.

Act VI: Enter DHH — The Architectural Enforcer

October 17, 2024: First Contact

David Heinemeier Hansson, creator of Ruby on Rails and co-founder of Basecamp, made his first contribution with characteristic pragmatism:

commit 8504e911a
Author: David Heinemeier Hansson
Date: 2024-10-17

    No longer used

He deleted an unused image file. It was a statement of intent.

October 19, 2024: Rails 8 and Caching Blitz

Within two days, DHH’s fingerprints were everywhere:

commit 23d81c07c - "Use Rails 8.0 rc1"
commit 5d06e5449 - "Etag the bubbles#show"
commit cd14fda39 - "Cache bubble partial on itself"
commit 32d1792cb - "Fetch bubbles index with multiget cache"

He upgraded the entire application to Rails 8 release candidate and systematically added HTTP caching throughout.

The War on “Anemic” Code

DHH’s most distinctive contribution was his crusade against what he called “anemic” code — thin wrappers that explain nothing and add needless indirection. He used this term 15 times in commit messages:

commit 7d86aae67 - "Inline anemic method"
commit 0edfc337c - "Inline anemic partials"
commit 9913853cc - "Remove anemic concern"
commit a1543f266 - "Inline anemic helper method with no additional explaining purpose"
commit cacee0feb - "Remove anemic scope"
commit a5df54015 - "Remove anemic and indirect method that explained nothing"

Philosophy: Code should either add explanatory value OR hide implementation complexity. Thin wrappers that do neither are “anemic” and should be eliminated.

April 2025: The Great Refactoring

Then came April 2025. DHH made 323 commits in a single month — 55% of his total contributions compressed into 30 days.

This was a surgical strike. He:

• Removed the entire Boosts feature (760cbb6c9) — 299 lines across 27 files, gone
• Eliminated activity scoring (82c9b011a, 7c76bdd96, 1114679c2)
• Extracted RESTful controllers from overloaded ones (43069b1ea, bced7405d)
• Enforced transaction discipline (7124835e6 — “No long transactions!”)

His commit messages tell the story:

commit 966aa51a3 - "Get rid of unnecessary touch jobs"
commit 255435a38 - "No need for a non-standard factory method for something this simple"
commit 393e5fd3d - "Don't want to ship with this wart"
commit e3f7930dc - "Unlikely we are going to need this"

In DHH’s philosophy: deletion is a feature, not a bug.

Act VII: The Final Transformation — Bubbles Become Cards

April 9, 2025: The Kanban Awakening

After 10 months as “Bubbles,” another transformation:

commit 723e6d94f
Date: 2025-04-09

    Rename bubbles => cards

333 files changed. “Pop” (completing a bubble) became “Closure” (closing a card). The playful metaphor gave way to task management vocabulary.

September-November 2025: The Column System

The final architectural piece:

commit cd025447f (September 2025)

    Add basic column models and script to migrate

Fizzy had become a kanban board. Cards lived in columns. Columns could be customized, colored, reordered. The application had evolved from “bugs on a windshield” to a sophisticated project management tool.

commit 2af7a9f40 (November 5, 2025)

    Merge PR #1498: rename-boards

Collections became Boards. The transformation was complete:

Original (July 2024):

• Splats on a Windshield

Final (November 2025):

• Cards → Columns → Boards → Accounts

Act VIII: The Features That Didn’t Make It

Fizzy Ask — The AI That Was Removed

commit 9a02716a4 - "Add Fizzy Ask" (PR #857)
commit 1263ca582 - "Give Fizzy Ask context about who it's talking to"
commit fc0fccef1 - "Show only published cards to Fizzy Ask"
commit 24cb5da19 - "Make Fizzy Ask staff-only"
commit 9317a8257 - "Remove Fizzy Ask"

A Claude-powered AI assistant that could answer questions about project content. Born, restricted to staff, then removed entirely. Perhaps replaced by the more ambitious MCP (Model Context Protocol) integration — making Fizzy AI-native at the protocol level rather than bolting on a chatbot.

Reactions — The Feature That Came Back

commit [initial] - Reactions feature added
commit bf44ad973 - "Revert reactions"
commit a9bb534d8 - "Reactions polish" (PR #1734)

Emoji reactions for cards and comments. Added. Removed. Then added again. The git history shows healthy debate — not everything that ships stays shipped, and not everything removed stays gone.

Custom Views — Replaced by Simplicity

commit 86332e3a2 - "Remove custom views UI"
commit e4fb0e831 - "Add static quick filters"

Saved custom views were replaced by ephemeral quick filters. Complexity gave way to simplicity.

Workflows — Too Much Structure

commit 24f1394ca - "Remove workflows code, remove more unused code"
commit c99084c65 - "No workflows, columns will be ad-hoc"

Predefined workflows with stages were removed in favor of ad-hoc column organization. Users would create their own structure.

Act IX: The Experimental Frontier

The MCP Branch — AI-Native by Design

commit fa16de7bb - "Add bubbles list as a tool for MCP clients"
commit fbd9b6302 - "Add an MCP manifest ala PWA manifests"
commit de6f782ca - "Add MCP Identification to all requests"

The MCP (Model Context Protocol) branch represents cutting-edge AI integration — allowing Claude and other AI assistants to interact with Fizzy programmatically. An .mcp.json manifest advertises Fizzy’s capabilities to AI clients.

Status: Removed from main, but the infrastructure remains fascinating. This is one of the earliest explorations of making traditional web applications AI-native.

Mobile Column View — The Unsolved Problem

Branches:
- origin/mobile-column-view-redux
- origin/mobile-column-view-redux+contained-scrolling
- origin/test-swiping-columns-on-mobile
- origin/mobile-app/scoped-stylesheets

Multiple parallel branches exploring different approaches to mobile column navigation. Scroll snapping. Contained scrolling. Swipeable columns. The problem remains unsolved — there’s no “one true way” for mobile kanban navigation.

SQLite Support — Database Flexibility

commit a2333d9a3 - "Add SQLite support"
commit 12de56417 - "Remove MySQL from default local development setup"

Making Fizzy work with SQLite in addition to MySQL. Simpler local development. Better portability. The search index was even sharded into 16 tables (search_records_0 through search_records_15) for scale.

Act X: The Road to Open Source

November 22-28, 2025: The Great Extraction

commit e1e9a01 - "Make open source the default"
commit 8724963 - "Bring vanilla versions for Dockerfile and deploy config"
commit 2c70793 - "Move kamal deploy config to the gem"
commit 0328149 - "Initial github action setup"

The proprietary SAAS features were extracted into a separate gem. What remained was a clean, open-source Rails application.

November 28, 2025: Public Release

commit fa1fe47
Date: 2025-11-28

    Initial README and LICENSE

After 18 months of development, 8,152 commits, and countless pivots, Fizzy became open source.

Epilogue: The Cast of Characters

The Contributors (by commit count)

1. Jason Zimdars (2,217 commits) — The visual architect. From “Let’s try bubbles” to pixel-perfect polish.

2. Jorge Manrubia (2,053 commits) — The engineering backbone. Consistent, prolific, essential.

3. Andy Smith (1,007 commits) — Front-end craftsmanship and UI refinement.

4. Mike Dalessio (875 commits) — Infrastructure, performance, the recent dashboard work.

5. David Heinemeier Hansson (586 commits) — The architectural enforcer. Rails modernization and the war on anemic code.

6. Kevin McConnell (351 commits) — Started it all with “New Rails app.”

7. Jose Farias (341 commits) — Feature development and testing.

8. Stanko K.R. (239 + 54 commits) — Security hardening and webhook restrictions.

9. Jeffrey Hardy (100 commits) — Early infrastructure and modernization.

10. Jason Fried (7 commits) — The occasional “Small copy adjustment” from the CEO.

The Dramatic Moments

• July 24, 2024: “Handful of tweaks before all-hands” — Demo day pressure
• July 31, 2024: “Let’s try bubbles” — The visual pivot
• September 4, 2024: “Splat -> Fizzy” — Finding the name
• April 2025: DHH’s 323-commit refactoring blitz
• October 2025: “Remove Fizzy Ask” — The AI feature that didn’t survive
• November 28, 2025: “Initial README and LICENSE” — Going public

Technical Appendix: The Architecture Evolution

Data Model Timeline

July 2024 (v0.1):

Splat (title, body, color)
  └── Categories
  └── Boosts
  └── Comments

September 2024 (v0.2):

Project (name)
  └── Bubble (title, body, color)
       └── Tags
       └── Comments
       └── Boosts

November 2025 (v1.0):

Account
  └── Board (name, settings)
       └── Column (name, color, position)
            └── Card (title, status, due_on)
                 ├── Comments
                 ├── Assignments
                 ├── Attachments
                 ├── Tags
                 ├── Steps (checklist)
                 ├── Watches
                 └── Events (audit trail)

Key Technology Decisions

1. Rails 8.x — Always on the latest, sometimes ahead of stable
2. Hotwire (Turbo + Stimulus) — No heavy JavaScript framework
3. Solid Queue & Solid Cache — Rails-native background jobs and caching
4. SQLite + MySQL support — Database flexibility
5. Kamal deployment — Modern container orchestration
6. UUID primary keys — Using UUIDv7 for time-ordering
7. Multi-tenancy — Account-based data isolation

Conclusion: What Fizzy Teaches Us

The story of Fizzy is the story of discovery through building. The team didn’t know they were building a kanban board when they started with “splats on a windshield.” They found out through iteration.

Key lessons:

1. Names matter, but they can change. Splat → Bubble → Card. Project → Bucket → Collection → Board. The right name emerges through use.

2. Deletion is a feature. Boosts, Fizzy Ask, custom views, workflows — removing the wrong features is as important as adding the right ones.

3. Architecture evolves. The final column-based kanban system looks nothing like the original flat list of splats.

4. DHH’s philosophy: Remove anemic code. Keep transactions short. Use the latest Rails. Delete more than you add.

5. Design drives naming. “Fizzy” emerged from the visual metaphor of bubbles puffing up and floating away — the design informed the brand.

6. Open source takes extraction. 18 months of SAAS development needed careful separation before the core could be shared.

The git history of Fizzy is a masterclass in iterative product development. 8,152 commits. 25+ contributors. 18 months. One application that discovered its identity through the act of creation.

“Let’s try bubbles.” — Jason Zimdars, July 31, 2024

Commit Reference Index

Documentary compiled December 2, 2025 Based on analysis of the Fizzy git repository

For most teams, webhooks are the bridge between the issues you track and the tools you already rely on. They let you push events into chat, incident tools, reporting pipelines, and anything else that speaks HTTP. If you are evaluating Fizzy or planning an integration, understanding what these webhooks can do will save you time.

I also put together a short PDF with the full payload structure and example code, which I link at the end of this post if you want to go deeper.

What could we build?

Here are a few ideas for things you could build on top of Fizzy’s events:

• A team metrics dashboard that tracks how long cards take to move from card_published to card_closed and which assignees or boards close issues the fastest.
• Personal Slack or Teams digests that send each person a daily summary of cards they created, were assigned, or closed based on card_published, card_assigned, card_unassigned, and card_closed events.
• A churn detector that flags cards that bounce between columns or get sent back to triage repeatedly using card_triaged, card_sent_back_to_triage, and card_postponed.
• A cross-board incident view that watches card_board_changed to keep a separate dashboard of cards moving into your incident or escalation boards.
• A comment activity stream that ships comment_created events into a search index or knowledge base so you can search discussions across boards.

If you want to go deeper, you can also build more opinionated tools that surface insights and notify people who never log in to Fizzy:

• Stakeholder status reports that email non-technical stakeholders a weekly summary of key cards: what was created, closed, postponed, or sent back to triage on their projects. You can group by label, board, or assignee and generate charts or narrative summaries from card_published, card_closed, card_postponed, and card_sent_back_to_triage events.
• Capacity and load alerts that watch for people who are getting overloaded. For example, you could send a notification to a manager when someone is assigned more than N open cards, or when cards assigned to them sit in the same column for too long without a card_triaged or card_closed event.
• SLA and escalation notifications that integrate with PagerDuty or similar tools. When certain cards (for example, labeled “Incident” or on a specific board) are not closed within an agreed time window, you can trigger an alert or automatically move the card to an escalation board using card_postponed, card_board_changed, and card_closed.
• Customer-facing status updates that keep clients in the loop without giving them direct access to Fizzy. You could generate per-customer email updates or a small status page based on events for cards tagged with that customer’s name, combining card_published, card_closed, and comment_created to show progress and recent discussion.
• Meeting prep packs that assemble the last week’s events for a given board into a concise agenda for standups or planning meetings. You can collate newly created cards, reopened work, and high-churn items from card_published, card_reopened, card_triaged, and card_sent_back_to_triage, then email the summary to attendees before the meeting.

Here is how to set it up.

Setting up webhooks

Step 1. Visit a board and click the Webhook icon in the top right.

Step 2. Give the webhook a name and the payload URL and select the events you want to be alerted to.

Step 3. Once the webhook saves you will see a summary of how it is setup and most importantly the webhook secret which you will need for your handler for securing the webhook. There is also a handy event log showing you when an event was delivered.

Since I like to tinker with these sorts of things, I built a small webhook receiver to capture and document the payload structures.

The Webhook System

Fizzy sends HTTP POST requests to your configured webhook URL when events occur. Each request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. The verification process is straightforward:

require 'openssl'

def verify_signature(body, signature, secret)
  expected = OpenSSL::HMAC.hexdigest('SHA256', secret, body)
  OpenSSL.secure_compare(expected, signature)
end

Event Types

Fizzy covers the essential card lifecycle events:

• card_published - new card created
• card_triaged - card moved to a column
• card_assigned / card_unassigned - assignment changes
• card_closed - card moved to Done
• card_reopened - card reopened from Done
• card_postponed - card moved to Not Now
• card_sent_back_to_triage - card moved back to Maybe?
• card_board_changed - card moved to different board
• comment_created - comment added to a card

How I captured the payloads

The approach was straightforward: I wrote a small Ruby script using WEBrick to act as a webhook receiver. The script listens for incoming POST requests, verifies the HMAC-SHA256 signature (using the webhook secret Fizzy provides when you configure webhooks), and saves each event as a separate JSON file with a timestamp and action name. This made it easy to review and compare the different event types later.

To expose my local server to the internet, I used ngrok to create a temporary public URL pointing to port 4002. I then configured Fizzy’s webhook settings with this ngrok URL and selected the event types I wanted to capture.

With everything set up, I went through Fizzy’s UI and manually triggered each available event: creating cards, adding comments, assigning and unassigning users, moving cards between columns and boards, marking cards as done, reopening them, postponing cards to “Not Now”, and sending cards back to triage. Each action fired a webhook that my script captured and logged.

In total, I captured 13 webhook deliveries covering 10 different action types. The only event I could not capture was “Card moved to Not Now due to inactivity” — Fizzy triggers this automatically after a period of card inactivity, so it was not practical to reproduce during this test.

Gotchas and Observations

Card body content is not included. The card object in webhook payloads only contains the title, not the full description or body content. Comments include both plain_text and html versions, but cards do not. Since Fizzy doesn’t have a public API (DHH is working on it), you can’t fetch the full card content programmatically - you’ll need to use the url field to view the card in the browser.

Column data is only present when relevant. The column object only appears on card_triaged, card_closed, and card_reopened events - the events where a card actually moves to a specific column.

IDs are strings, not integers. All identifiers in the payload are strings like "03f25q9q7bw7t3206v9ttiy53", not numeric IDs.

Documentation

I created a short webhook documentation based on this research: FIZZY_WEBHOOKS.pdf

It includes the full payload structure, all event types with examples, and code samples for signature verification in both Ruby and JavaScript. Hopefully this helps you get up and running with Fizzy’s webhooks. Let me know if you discover additional events or edge cases.

Since the source code is available, you can also submit PRs to fix or enhance aspects of the webhook system if you find something missing or want to contribute improvements.

The Problem

Mermaid diagrams are text-based and version-controllable, which makes them useful for documentation. The syntax can be finicky:

• Missing arrows or incorrect arrow types
• Unbalanced brackets
• Invalid node names
• Typos in keywords

A diagram might look correct in markdown but fail to render. Without validation, you discover this only after the work is complete.

The Solution

Skills in Claude Code are markdown files that provide instructions for specific tasks. They can be invoked manually or triggered automatically when Claude detects a relevant situation.

Here is the mermaid validation skill:

---
name: mermaid-validator
description: Automatically validate mermaid diagrams after creating or editing them in markdown files
---

# When to Use This Skill

**Proactively use this skill after:**
- Creating new mermaid diagrams in markdown files
- Editing existing mermaid diagrams
- User asks to validate/check mermaid diagrams

**Always validate before completing the task.**

# Instructions

1. Read the markdown file (use the file from context or ask user which file to validate)
2. **Run validation** using: `mmdc -i <file-path> -o /tmp/mermaid-validation.svg 2>&1`
3. **Report validation results**:
   - If valid: Confirm the diagram is valid and exit
   - If invalid: Show the errors found and explain what's wrong
4. **Fix the issues** automatically (invalid diagrams have no value)
5. **Re-validate** to confirm the fix worked
6. Repeat steps 4-5 until there are no validation issues

Prerequisites

The skill uses mmdc (mermaid CLI) for validation. Install it globally:

npm install -g @mermaid-js/mermaid-cli

Setting It Up

Create the skill file at:

~/.claude/skills/mermaid-validator/SKILL.md

Or in your project at:

.claude/skills/mermaid-validator/SKILL.md

How It Works

When Claude creates or edits a markdown file containing mermaid diagrams:

1. The skill is automatically invoked
2. Validation runs via mmdc
3. Errors are fixed and re-validated
4. Success is only reported when diagrams render correctly

Invalid diagrams have no value. Rather than leaving validation to the user, Claude verifies its own work.

Why This Matters

Manual validation requires remembering to ask for it every time. Skills make validation automatic and consistent. Every diagram gets checked, and errors are fixed before you see them.

The pattern applies beyond mermaid diagrams. Any output that can be validated by a tool is a candidate for a validation skill. If a tool can identify errors, Claude can fix them before marking the task complete.

Let me know if you have questions about setting this up.

Update (August 26, 2025): Sonic has been confirmed as the new Grok Code model and is now officially available today! What was once a “stealth” model is now xAi’s publicly released coding assistant.

A new stealth model called Sonic has quietly appeared in places like Opencode and Cursor, and it’s rumored to be xAi’s Grok coding model. I spent a full day working with it inside Opencode, replacing my usual Claude Sonnet 4 workflow — and came away impressed. The short version? It feels like Sonnet, but turbocharged.

Getting Access

Sonic showed up in Opencode’s model selector — no special invite required. Selecting it as the active model made it fully functional, with no setup beyond choosing it in the dropdown. During this stealth period it’s free to use and offers a massive 256,000 token context window. I didn’t encounter any rate limits or throttling all day.

First Test

Instead of a contrived “hello world,” I dropped Sonic into my real workflow. Where I’d usually use Sonnet 4, I asked Sonic to help me build a new Training Center CRUD feature in a Ruby on Rails application.

It generated the models, migrations, controllers, and views exactly as expected — and most importantly, it did it fast. Text streamed out so quickly it was hard to keep up. Compared to Claude Code, I’d estimate 3x faster tokens per second, consistently.

That was my wow moment: speed without sacrificing accuracy. It nailed the Rails conventions and felt like a drop-in Sonnet replacement.

My Standard Benchmark

My go-to evaluation prompt for coding models is: “Tell me about this codebase and what the most complex parts are.” On my legacy Rails codebase, Sonic immediately identified the correct overloaded model as the main complexity hotspot, and even suggested ways to refactor it.

The result was near identical in quality to what I’d get from Sonnet or even Opus — but again, the response flew back near-instantly. For day-to-day comprehension and reasoning, Sonic seems to match the best while dramatically cutting wait time.

Comparison to Claude Sonnet

• Reasoning & Accuracy: Nearly identical to Sonnet. No hallucinations, no weird Rails missteps.
• Personality: Very similar, though Sonic felt a bit more positive and agreeable to suggestions.
• Speed: The standout. At least 3x faster than Claude Code/Sonnet, with the speed holding steady across short and long generations.
• Where Sonnet Might Still Win: Hard to say yet — I didn’t hit any reasoning failures, but Sonnet have a longer track record of reliability under heavy workloads.

Bottom line: if you’re used to Sonnet, Sonic feels like the same experience at high speed.

Pricing and Availability

Right now Sonic is free to use in Opencode during its stealth rollout. No public pricing details are available yet, but if it undercuts Sonnet, it could be a winner.

I haven’t seen any rate limits or regional restrictions. Cursor users also report seeing Sonic available as a selectable model.

Initial Verdict

After a full day of work, I would — and did — ship production code with Sonic. It handled CRUD features, comprehension of a large legacy codebase, and various refactors without issue.

The real differentiator is speed. If Sonnet is your baseline, Sonic offers the same reasoning ability but with response times that feel instantaneous. Unless something changes in pricing or reliability, this could easily become my daily driver.

Quick Reference

• Access: Select “Sonic” in Opencode’s model selector (no invite required during stealth)
• Pricing: Free during stealth; official pricing TBD
• Best for: Day-to-day coding tasks, CRUD features, codebase comprehension, Rails development
• Avoid for: Nothing obvious yet — but keep human oversight on critical code
• API docs: Not yet public
• Hot take: As I posted on X, this feels like my Sonnet replacement should I be forced to not have Sonnet. @robzolkos