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 session IDs or 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. Fetches sessions by explicit IDs, or searches the Harmonica API with your configured queries
2. Validates search results and 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 (summaries only by default — individual responses are opt-in)
5. Writes markdown files to the output directory

Configuration

harmonica.config.json:

{
  "sync": {
    "sessionIds": ["hst_abc123", "hst_def456"],
    "search": [],
    "minParticipants": 1,
    "requireSummary": true
  },
  "output": {
    "dir": "sessions",
    "filename": "{{date}}-{{id}}.md",
    "template": "./session-template.md"
  }
}

Session selection

Use sessionIds (recommended) to sync specific sessions by ID, or search for query-based discovery. When sessionIds is provided, search queries are ignored.

Privacy note: Search queries use the Harmonica API's full-text search, which may return sessions beyond your own depending on your API key's scope. Use sessionIds when syncing to public repositories.

Field	Description	Default
sync.sessionIds	Explicit session IDs to sync (recommended)	—
sync.search	API search queries (used when no sessionIds)	—
sync.keywords	Filter on topic/goal/context text (whole-word match)	all results accepted
sync.minParticipants	Skip sessions below this count	1
sync.requireSummary	Only sync sessions with a summary	true
sync.includeResponses	Include individual participant responses	false
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)

Roadmap

• Research sync pipeline — A --mode research for complex research projects where one session produces many output files. Extracts participant data, maps messages to problems/solutions (LLM-assisted or rule-based), computes metrics (breadth, depth, urgency scores), and renders 50+ files across wiki pages and dashboards — all from a single canonical data file. Includes a human-in-the-loop reconciliation step before any writes. (Design doc)
• Git repo as session context — Feed repo content (previous sessions, workshop notes, artifacts, consensus) back into new Harmonica sessions as facilitator context. Closes the loop: sessions produce markdown → markdown informs future sessions. Config-driven context assembly in harmonica.config.json defines rules for what to send (e.g., "include all artifacts, last 3 workshops, latest consensus") and a --context flag assembles and pushes to the Session Context Sources API (HAR-94). Without this, communities must manually pick documents per session or write custom CI scripts.
• Incremental updates — Re-sync sessions that changed since last run (based on updated_at or response count) instead of skipping already-synced sessions entirely. Active sessions get new responses over time — the archive should reflect that. (HAR-339)
• Webhook trigger — React to Harmonica webhooks when a session completes or gets new responses, instead of polling every 6 hours. Faster updates, fewer wasted CI runs. (HAR-340)
• Auto-generate emerging consensus — Post-sync synthesis step that reads all content in the output directory (sessions, workshops, artifacts) and writes a consensus summary to a data file (e.g., _data/consensus.yml) for static site generators. Supports BYOM (Bring Your Own Model): use Harmonica's API by default, or configure your own LLM provider in harmonica.config.json. (HAR-338)

License

MIT