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) |

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