harmonica-sync

Sync Harmonica deliberation sessions to markdown files. Run locally or in CI to keep a structured archive of your sessions in a git repo, Quartz wiki, or static site.

Quick Start

# 1. Scaffold config and template
npx harmonica-sync --init

# 2. Edit harmonica.config.json with your search queries

# 3. Set your API key (from Harmonica dashboard → Settings → API Keys)
export HARMONICA_API_KEY=hm_live_...

# 4. Sync
npx harmonica-sync

How It Works

1. Searches the Harmonica API with your configured queries
2. Filters by keywords, participant count, and summary availability
3. Skips sessions already in the output directory (idempotent)
4. Renders each session through a Mustache template
5. Writes markdown files to the output directory

Configuration

harmonica.config.json:

{
  "sync": {
    "search": ["community feedback", "retrospective"],
    "keywords": ["our-org", "team"],
    "minParticipants": 1,
    "requireSummary": true
  },
  "output": {
    "dir": "sessions",
    "filename": "{{date}}-{{id}}.md",
    "template": "./session-template.md"
  }
}

Field	Description	Default
sync.search	API search queries (required)	—
sync.keywords	Filter on topic/goal/context text	all results accepted
sync.minParticipants	Skip sessions below this count	1
sync.requireSummary	Only sync sessions with a summary	true
output.dir	Output directory	sessions
output.filename	Filename template ({{date}}, {{id}}, {{slug}})	{{date}}-{{id}}.md
output.template	Path to Mustache template	built-in Quartz-compatible

Templates

The default template produces Quartz/Hugo/Jekyll-compatible markdown with YAML frontmatter. Customize it by editing the session-template.md generated by --init.

Available template variables:

Variable	Type	Description
topic	string	Session topic
date	string	ISO date (YYYY-MM-DD)
id	string	Session ID
participant_count	number	Number of participants
status	string	Session status
goal	string	Session goal
critical	string/null	Critical question
context	string/null	Session context
summary	string/null	AI-generated summary
tags	string[]	Matched search queries
responses	boolean	Whether responses exist
participants	array	Participant responses
participants[].number	number	Participant number (1-indexed)
participants[].messages	array	User messages

CI Usage

GitHub Actions

name: Sync Harmonica Sessions
on:
  schedule:
    - cron: '0 */6 * * *'
  workflow_dispatch:
permissions:
  contents: write
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync sessions
        env:
          HARMONICA_API_KEY: ${{ secrets.HARMONICA_API_KEY }}
        run: npx harmonica-sync
      - name: Commit new sessions
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add sessions/
          git diff --cached --quiet || git commit -m "Sync Harmonica sessions" && git push

CLI Reference

npx harmonica-sync                     # sync using ./harmonica.config.json
npx harmonica-sync --config path/to    # custom config path
npx harmonica-sync --init              # generate starter config + template
npx harmonica-sync --help              # show help

Environment Variables

Variable	Required	Description
HARMONICA_API_KEY	Yes	API key from Harmonica dashboard
HARMONICA_API_URL	No	API base URL (default: https://app.harmonica.chat)

License

MIT