harmonica-chat

Design and manage Harmonica deliberation sessions from your coding agent. Guided session design, template matching across the live platform library, full lifecycle commands (check, summary, edit, review, follow-up), and post-session facilitation-quality analysis.

Harmonica is a structured-conversations platform where groups align via AI-facilitated async conversations. You create a session with a topic and goal, share a link with participants, and each person has a private 1:1 chat with an AI facilitator. Responses are then synthesized into actionable insights. Learn more.

Unlike a one-shot session creator, harmonica-chat is a guided designer — it walks you through template selection, goal refinement, and context calibration, then handles the full lifecycle from creation through follow-up.

Works with

• Claude Code — fully supported today, via ~/.claude/skills/harmonica-chat/. Quick install below.
• Cursor, Codex, Grok Build, OpenCode, Pi agent, … — the skill is plain Markdown using the Agent Skills format. Manual install (copy SKILL.md + reference/ to the agent's skills directory) should work. OpenCode-specific MCP mapping is documented in reference/opencode.md; first-class installers for other harnesses are tracked in HAR-1231.

Prerequisites

• A Harmonica account — sign up free if you don't have one.
• An API key — generate at Profile > API Keys. You'll get a hm_live_... value.
• Node.js on PATH for the installer's permissions update. Hosted MCP does not require a local MCP process.
• Claude Code on PATH for the installer; manual installation works with other agents.

Installation

New installations use the hosted MCP endpoint in Harmonica Pro: https://app.harmonica.chat/api/mcp/mcp. Existing harmonica registrations are preserved, including local npm and self-hosted connections.

Quick install — bash (macOS / Linux / Git Bash on Windows)

export HARMONICA_API_KEY=hm_live_...
bash <(curl -fsSL https://raw.githubusercontent.com/harmonicabot/harmonica-chat/master/install.sh)

Quick install — PowerShell (Windows)

$env:HARMONICA_API_KEY = 'hm_live_...'
irm https://raw.githubusercontent.com/harmonicabot/harmonica-chat/master/install.ps1 | iex

What the installer does

1. Verifies the claude CLI and node are available. A key is required only when creating a new MCP registration.
2. Registers hosted HTTP MCP in Claude Code's user scope, with Authorization set to the literal Bearer ${HARMONICA_API_KEY} reference. An existing registration is left unchanged; the key is never passed as a CLI argument or printed on failure.
3. Installs SKILL.md + 12 reference/*.md files to ~/.claude/skills/harmonica-chat/.
4. Pre-approves the 6 read-only mcp__harmonica__* tools (list_sessions, search_sessions, get_session, get_responses, get_summary, list_telegram_groups) by adding them to ~/.claude/settings.json permissions.allow — fewer prompts during use; mutations (create_session, update_session) still require confirmation.
5. Removes the legacy v2.x slash-command install at ~/.claude/commands/harmonica-chat.md if present.
6. Verifies the MCP is registered.

Keep HARMONICA_API_KEY available in the environment that launches Claude Code, including after restarting it: the installer stores a reference, not the key. Both installers honor CLAUDE_CONFIG_DIR for a custom Claude Code profile. Restart Claude Code from that environment, check the connection with /mcp, then invoke /harmonica-chat or describe what you want to facilitate. Registration checks alone do not verify a live API connection.

OpenCode installation

OpenCode can use the shared skill files directly. Copy SKILL.md, reference/, and reference/opencode.md into the OpenCode skills directory, configure hosted MCP in OpenCode V2's settings under mcp.servers, and reload the connection:

{
  "mcp": {
    "servers": {
      "harmonica": {
        "type": "remote",
        "url": "https://app.harmonica.chat/api/mcp/mcp",
        "oauth": false,
        "headers": { "Authorization": "Bearer {env:HARMONICA_API_KEY}" }
      }
    }
  }
}

Start OpenCode with HARMONICA_API_KEY in its environment. This example uses the OpenCode V2 configuration format. V1 places harmonica directly under mcp instead. The skill uses tools.harmonica.<operation> for Harmonica calls through Code Mode.

Continue onboarding through hosted MCP (Claude Code or OpenCode)

If the Harmonica welcome journey offers AI-assistant access, use its dedicated, revocable setup key to configure the hosted MCP endpoint, https://app.harmonica.chat/api/mcp/mcp, in the chosen harness. Install the harmonica-chat skill alongside it; the MCP connection supplies tools, while the skill supplies the guided creation and fingerprinted handoff. These are separate from any BYOM provider credential.

Use the onboarding screen's harness-specific recipe rather than pasting a key into chat, a repository file, a URL, or a command-line argument. Keep the bearer in your local environment and the harness configuration as an environment-variable reference; reload the harness after installation. With this skill installed, ask: Continue my Harmonica onboarding for flow <flow-id> (use the flow ID shown in the browser). The skill calls continue_onboarding, guides you back to /welcome if browser steps remain, and asks for confirmation before creating your first session from the saved handoff. If a creation response was lost, it returns the already attributed session rather than creating another.

Existing local-npm users: ordinary session-design commands still work with harmonica-mcp, and the installers preserve that connection. The onboarding flow specifically requires the hosted endpoint; do not substitute local npm MCP for it or switch a working local setup silently. The onboarding UI/flag is a separate future release; this skill update only provides the continuation route when a host already has a compatible saved flow.

Manual installation

If you can't run the script or are installing for a non-Claude-Code agent:

1. Load HARMONICA_API_KEY into the environment that starts your agent, then configure hosted MCP. For Claude Code in bash:

   claude mcp add-json harmonica '{"type":"http","url":"https://app.harmonica.chat/api/mcp/mcp","headers":{"Authorization":"Bearer ${HARMONICA_API_KEY}"}}' -s user

   (or the equivalent for your agent — see its docs for MCP configuration.)
2. Copy SKILL.md and the reference/ directory to your agent's skills location (Claude Code: ~/.claude/skills/harmonica-chat/).
3. Restart your agent.

Local stdio and self-hosted compatibility

Use harmonica-mcp when your client requires stdio or you connect to an OSS/self-hosted REST API. It requires Node.js 20 or newer; set HARMONICA_API_URL to your own instance as described in its README. This package receives security and compatibility fixes; new MCP capabilities are developed in Pro and are not automatically backported. There is no requirement to migrate a working local connection to update this skill.

Updating from v2.x

v3.0.0 moved the install path from ~/.claude/commands/harmonica-chat.md to ~/.claude/skills/harmonica-chat/SKILL.md + reference/. The v3.1+ installer removes the legacy file automatically. Re-run the quick-install command.

Updating (v3.0.0+)

The skill checks for updates on each run and suggests updating if a newer version is available. You can also update manually with the same quick-install command.

Why pre-approve read-only MCP tools?

By default Claude Code prompts before running any MCP tool. For harmonica-chat that means a prompt every time it lists or fetches a session — fast to dismiss but death by paper cuts during a check / summary / review flow. The installer pre-approves the 6 read-only tools so you only get prompted for mutations (creating, updating, sending chat messages). To opt out: remove the entries from ~/.claude/settings.json permissions.allow after install.

Usage

Invoke as /harmonica-chat (the skill is exposed as a slash command). The entry router parses your input and loads the matching subcommand reference on demand.

Guided session design

/harmonica-chat

Walks you through the full design flow: intent, template matching, topic, goal, context, critical question, cross-pollination, results visibility, and confirmation. Each question asked one at a time.

Accelerated creation

/harmonica-chat "Q1 retrospective"

Topic upfront skips the intent / topic questions. Template suggestion + faster confirm flow.

Project-aware creation

/harmonica-chat "retro on the API redesign" --project harmonica-web-app

Reads the project's CLAUDE.md and recent git history to auto-generate session context. Suggests a session type based on recent activity patterns.

Session lifecycle

/harmonica-chat status                    # List your recent sessions
/harmonica-chat check "Q1 retro"          # Check participant progress and themes
/harmonica-chat summary "Q1 retro"        # Get the AI-generated synthesis
/harmonica-chat edit "Q1 retro"           # Update topic / goal / context / prompt
/harmonica-chat review "Q1 retro"         # Analyze transcripts + propose prompt fixes
/harmonica-chat follow-up "Q1 retro"      # Design a follow-up session

Architecture

v3.0.0 split the skill into a thin entry router (SKILL.md) plus lazy-loaded subcommand references in reference/. The router parses your input, decides which reference to load, and follows that reference's instructions.

harmonica-chat/
├── SKILL.md                  Entry router: prerequisites, design laws, routing, commands menu
└── reference/
    ├── design.md             Guided session design (14 steps)
    ├── accelerated.md        Topic-upfront flow + project-aware creation
    ├── status.md             List recent sessions
    ├── check.md              Thematic preview of responses
    ├── summary.md            AI-generated synthesis
    ├── edit.md               Update session metadata
    ├── review.md             Facilitation quality analysis + prompt fixes
    ├── follow-up.md          Design a next-step session
    ├── onboarding.md         Resume a saved hosted-MCP onboarding flow
    ├── opencode.md           Harness-specific MCP operation mapping
    ├── invitation.md         Post-creation invitation flow
    └── expertise.md          Soft-nudge session design heuristics

Templates are NOT hardcoded — fetched at runtime via mcp__harmonica__list_templates (harmonica-mcp ≥ 0.11.0). The Harmonica admin panel is the single source of truth.

This keeps context lean — the router loads when you invoke the skill, references load only when you use the matching subcommand. Inspired by pbakaus/impeccable's architecture.

Features

• Guided session design with template matching against the live Harmonica template library (fetched at runtime via list_templates; whatever the platform admin panel publishes is what you'll see)
• Session design expertise — goal quality nudges, context calibration, cross-pollination recommendations, constraint discovery
• Project-aware context — reads CLAUDE.md and git history to auto-fill session context
• Full session lifecycle — status, check, summary, edit, review, follow-up
• Facilitation quality review — analyzes transcripts across 5 dimensions, proposes specific prompt fixes with literal-quote citations (v2.11.0+)
• Telegram distribution — sessions can be announced to Telegram groups via the Harmonica bot
• Pre-session questions — configure what participants answer before the conversation; defaults are smart per distribution channel
• Invitation drafting with tone adapted to template type, plus integration with communication tools (Zapier, Slack) when available
• Community participation feed integration for publishing sessions to community dashboards

See Also

• Hosted MCP — recommended connection and current tools
• harmonica-mcp — maintained compatibility adapter for stdio and self-hosted REST APIs
• Harmonica docs — Platform documentation
• Harmonica — Main website

License

MIT