henkisdabro/message

Message Drafts

Bun-based preview server. Same fragment format, faster launch, nicer preview, auto-opens the browser, minimal Claude roundtrips.

Flow

1. Write the .fragment.md directly to data/writing/email_drafts/ in ONE Write tool call. Do NOT write the email body inline in your response before the Write call. Compose the draft mentally and write it straight to the file - the preview server renders it.
2. After the Write tool returns, read the URL the hook wrote:

   cat "${CLAUDE_PROJECT_DIR}/.claude/.message-preview-url" 2>/dev/null
   

3. Reply with only the preview URL and a one-line summary: Draft ready: email to Stuart re invoice follow-up → http://127.0.0.1:XXXX

The hook has already started the server and opened the browser by the time the Write tool returns. Do NOT run bun run serve.ts yourself. Do NOT call open <url>. Do NOT launch a second server. The browser is already open.

Always relay the preview URL to the user. Read it from .claude/.message-preview-url. If that file is empty or missing, the fragment was still written - point the user at the most recent .html sibling file.

On revision ("make it shorter", "change the tone"): use Read to load the fragment, Edit to apply changes. The server hot-reloads in <100 ms via WebSocket. Do not echo the revised body - just confirm the change and include the same URL. Do NOT start a new server — the existing one is still running.

Multiple concurrent drafts are fully supported. Each fragment gets its own server on its own port. All servers stay alive until the machine reboots. To find the URL for any previously opened draft, run:

python3 -c "
import json, sys
d = json.load(open('${CLAUDE_PROJECT_DIR}/.claude/.message-previews.json'))
print(d.get(sys.argv[1], 'not found'))
" "/absolute/path/to/draft.fragment.md"

Fragment format

Markdown with YAML frontmatter, same as /message v1.

---
to: [email protected]
subject: Subject line
cc: optional
bcc: optional
---

Body content in Markdown. Supports bold, italic, ~~strikethrough~~, headings, lists, blockquotes, code, tables, links. Embed raw HTML where Markdown falls short.

Required: to, subject. Do not use horizontal rules - they render poorly in email clients.

Tables - mandatory rules

When using tables, ALWAYS provide meaningful header names in the first row. Markdown's pipe-table syntax accepts blank headers (| | |) but the rendered output then shows a styled header row with no labels - confusing and unprofessional.

GOOD:

| Item | Amount |
|---|--:|
| Salary | $146,838.94 |

BAD - blank header row:

| | |
|---|--:|
| Salary | $146,838.94 |

If a table truly has no natural header, use descriptive labels like Item / Amount, Field / Value, Category / Notes. Header cells render with a light grey background (#f5f5f5) by default in both Gmail and Outlook to differentiate them from data rows.

File naming

data/writing/email_drafts/YYYY-MM-DD_recipient_subject.fragment.md
data/writing/email_drafts/YYYY-MM-DD_recipient_subject.html        # generated

Preview UI

The browser preview shows three tabs (Gmail / Outlook / WhatsApp) with keyboard shortcuts:

• G / O / W - switch tab
• C - copy current tab (rich HTML for Gmail/Outlook, text for WhatsApp)
• R - manual reload

Features: dark-mode aware, live WebSocket hot reload (<100 ms), mobile-responsive, copy buttons use the Clipboard API's HTML MIME type so paste into Gmail/Outlook preserves formatting as a single clean operation. Word and character counts update per tab. Build errors render as a red overlay with the exact message instead of a silent failure.

Edit flow

Edit the .fragment.md file. The server watches it via fs.watch and pushes a reload over WebSocket. No Bash command, no polling, no manual refresh. Latency from save to visible update: typically under 100 ms.

Env flags

• MESSAGE_NO_OPEN=1 - skip auto-opening the browser (useful in headless contexts)

Structure and tone

1. Lead with the point (request, update, instruction the recipient must act on)
2. Supporting detail (context, logistics)
3. Warm close (gratitude, relational content) just before the sign-off

Match the recipient's formality. British English (colour, analyse, organise, behaviour, centre).

Your defaults

Customise these for the user's context:

• From / reply-to: [email protected]
• Sign-off: Best,\n[Your Name]

After preview

Once the user has the preview URL, ask: "Would you like me to run the humanise skill on this draft to make it sound more natural?"

Post-draft actions

After a client-facing draft, prompt the user if they'd like to log this to a comms log or trigger any downstream actions in their project.

References

• references/formatting-rules.md - Gmail native HTML element reference (copied from v1)
• references/outlook-formatting.md - Outlook element styles and colour palette (copied from v1)

Development

Code lives in ${CLAUDE_PLUGIN_ROOT}/skills/message/scripts/. Run tests: cd .claude/skills/message && ~/.bun/bin/bun test. Build-only without serving: ~/.bun/bin/bun run scripts/serve.ts <fragment> --build-only.

Platform support

Works on macOS, Linux, WSL2 (Ubuntu), and native Windows (PowerShell). The hook is auto-serve-fragment.ts and runs under Bun on all platforms — bun must be on PATH. Browser opening: open on macOS, xdg-open on Linux, cmd.exe /c start on WSL2 (opens the Windows host browser via shared localhost), cmd /c start on Windows.