fizzy-md

README

fizzy-md

Transparent Markdown→HTML wrapper for Fizzy CLI.

Problem

AI agents naturally write in Markdown (**bold**, ## Headers), but Fizzy CLI requires HTML (<strong>bold</strong>, <h2>Headers</h2>). This creates friction — agents either:

• Forget and use Markdown (poor rendering in Fizzy UI)
• Manually convert to HTML (slows them down, breaks flow)
• Avoid rich formatting entirely (less informative cards)

Solution

fizzy-md is a transparent wrapper that accepts Markdown and converts it to HTML automatically. All fizzy commands work exactly as before — just write naturally!

Features

✅ Zero config — just works when installed
✅ 100% backward compatible — all fizzy commands pass through
✅ Fast — <100ms overhead, compiled Go binary
✅ Smart file detection — .md files auto-convert, .html files pass through
✅ CommonMark compliant — powered by goldmark

Installation

Option 1: Homebrew (macOS/Linux - Recommended)

brew tap zainfathoni/fizzy
brew install fizzy-md

Option 2: Pre-built binaries

Download the latest release for your platform from the releases page.

macOS:

# Intel
curl -L https://github.com/zainfathoni/fizzy-md/releases/latest/download/fizzy-md_Darwin_x86_64.tar.gz | tar xz
sudo mv fizzy-md /usr/local/bin/

# Apple Silicon (M1/M2/M3)
curl -L https://github.com/zainfathoni/fizzy-md/releases/latest/download/fizzy-md_Darwin_arm64.tar.gz | tar xz
sudo mv fizzy-md /usr/local/bin/

Linux:

# x86_64
curl -L https://github.com/zainfathoni/fizzy-md/releases/latest/download/fizzy-md_Linux_x86_64.tar.gz | tar xz
sudo mv fizzy-md /usr/local/bin/

# ARM64
curl -L https://github.com/zainfathoni/fizzy-md/releases/latest/download/fizzy-md_Linux_arm64.tar.gz | tar xz
sudo mv fizzy-md /usr/local/bin/

Windows:

Download fizzy-md_Windows_x86_64.zip from the releases page and extract to a directory in your PATH.

Option 3: go install

go install github.com/zainfathoni/fizzy-md@latest

Make sure ~/go/bin is in your PATH.

Option 4: Build from source

git clone https://github.com/zainfathoni/fizzy-md.git
cd fizzy-md
go build -o fizzy-md
sudo mv fizzy-md /usr/local/bin/

Usage

Use fizzy-md exactly like fizzy, but write Markdown instead of HTML:

Before (manual HTML)

fizzy card create \
  --title "Test Card" \
  --description "<h2>Overview</h2><p>This is <strong>important</strong>.</p><ul><li>Item 1</li><li>Item 2</li></ul>"

After (natural Markdown)

fizzy-md card create \
  --title "Test Card" \
  --description "## Overview

This is **important**.

- Item 1
- Item 2"

Works with files too

# Create card.md with Markdown content
fizzy-md card create --title "My Card" --description_file card.md

Optional: Alias for convenience

alias fizzy='fizzy-md'

Now all your fizzy commands automatically support Markdown!

Supported Flags

fizzy-md converts these flags automatically:

Flag	Description
--description "text"	Inline card description
--body "text"	Inline comment body
--description_file path	Card description from file
--body_file path	Comment body from file

File detection:

• .md files → convert to HTML
• .html files → pass through unchanged
• No extension → assume Markdown (agent-friendly default)

All other arguments pass through to fizzy unchanged.

Examples

Create a card with rich formatting

fizzy-md card create \
  --title "Bug Fix: Login Issue" \
  --description "## Problem

Users can't log in when password contains `&` character.

## Root Cause

- URL encoding not applied
- Special chars break form submission

## Fix

Added `encodeURIComponent()` to password field.

**Status:** ✅ Resolved"

Add a comment with code block

fizzy-md comment create \
  --card 42 \
  --body "Suggested fix:

\`\`\`javascript
const password = encodeURIComponent(input.value);
\`\`\`

This handles all special characters correctly."

Use a Markdown file

# notes.md
## Meeting Notes

- Discussed architecture
- Agreed on Go implementation
- Next: Build MVP

fizzy-md card create --title "Sprint Planning" --description_file notes.md

How It Works

1. Intercepts your command-line arguments
2. Detects Markdown in --description, --body, and file flags
3. Converts Markdown → HTML using goldmark
4. Passes through to real fizzy CLI
5. Preserves all other args/flags exactly

No modifications to fizzy-cli needed. Just a transparent wrapper!

Requirements

• Go 1.23+ (for building)
• fizzy-cli installed and in PATH
• macOS or Linux (Windows untested but should work)

Development

# Clone the repo
git clone https://github.com/zainfathoni/fizzy-md.git
cd fizzy-md

# Install dependencies
go mod download

# Build
go build -o fizzy-md

# Test
./fizzy-md card create --title "Test" --description "## Heading"

Inspiration

This tool follows the "agent-first" design principle from Steve Yegge's Software Survival 3.0:

"Agents always act like they're in a hurry, and if something appears to be failing for them, they will rapidly switch to trying workarounds. [...] Conversely, if you build the tool to their tastes, then agents will use the hell out of it."

Design principle: Minimize friction. Let agents write naturally (Markdown), handle the conversion transparently.

License

MIT License - see LICENSE file.

Credits

• Built with goldmark - The best Markdown parser in Go
• Wraps fizzy-cli by Rob Zolkos
• Created for the Autobots AI agent team

Contributing

Contributions welcome! Please open an issue or PR.

Future ideas:

• Homebrew tap for easier installation
• Windows support testing
• Upstream integration into fizzy-cli (if Rob Zolkos is interested)

---

Built with 🔧 by Wheeljack for AI agents everywhere.