Harmonica

Self-hosted AI facilitation for group sensemaking and deliberation

Website • Features • Quick Start • Changelog • Contributing

---

What is Harmonica?

Harmonica is an open-source platform for AI-facilitated group deliberation. Deploy it on your own infrastructure with your choice of LLM—whether self-hosted (Ollama, vLLM) or cloud providers (OpenAI, Anthropic, Google).

Instead of scattered feedback forms or unproductive meetings, participants engage in AI-facilitated conversations that surface the why behind their perspectives.

How it works:

1. Create a session with your discussion topic
2. Share the link with participants
3. Analyze the AI-generated synthesis with themes, priorities, and recommendations

Each participant has a private conversation with a custom AI facilitator. Harmonica then synthesizes all perspectives into actionable insights—surfacing consensus, highlighting tensions, and recommending next steps.

Features

• Conversational surveys — Go beyond checkboxes. AI-guided dialogue captures context and nuance.
• Async participation — No scheduling conflicts. Participants respond on their own time.
• Multi-language support — Participants can converse in their preferred language.
• Thematic synthesis — Automatically clusters responses into themes and priorities.
• Cross-pollination — Share insights across related sessions to build on each other's ideas.
• Workspaces — Organize sessions for teams, projects, or communities.
• Custom prompts — Tailor the AI facilitator's behavior to your context.
• File uploads — Attach PDFs and documents for context.

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL (or Neon for serverless)
• Auth0 account
• LLM provider (choose one):
  • Self-hosted: Ollama, vLLM, or any OpenAI-compatible endpoint
  • Cloud: OpenAI, Anthropic, Google, or other supported providers

Installation

git clone https://github.com/harmonicabot/harmonica-web-app.git
cd harmonica-web-app
npm install

Configuration

Copy the example environment file and fill in your credentials:

cp .env.example .env

Required variables:

Variable	Description
POSTGRES_URL	Neon/PostgreSQL connection string
AUTH0_*	Auth0 configuration (see Auth0 docs)
MAIN_LLM_PROVIDER	LLM provider: openai, anthropic, gemini, ollama, etc.
MAIN_LLM_MODEL	Model name (e.g., gpt-4o, claude-3-opus, llama3.2)

For embeddings, set OPENAI_API_KEY or configure an alternative embedding provider.

Database Setup

npm run migrate

Development

npm run dev

Open http://localhost:3000.

Tech Stack

Layer	Technology
Framework	Next.js 14 (App Router)
Database	PostgreSQL (Neon) + Kysely
Auth	Auth0
LLM	LlamaIndex with pluggable providers
Vector DB	Qdrant
UI	Tailwind CSS + Radix UI
Hosting	Vercel (or self-hosted)

LLM Providers

Harmonica supports multiple LLM backends through LlamaIndex:

Provider	Models	Notes
OpenAI	o3, GPT-4.5, GPT-4o	Cloud API
Anthropic	Claude Opus 4.5, Claude Sonnet 4	Cloud API
Google	Gemini 2.0 Flash, Gemini 2.5 Pro	Cloud API
Ollama	Llama 4, Qwen 3, DeepSeek-R1	Self-hosted
vLLM	Any supported model	Self-hosted, OpenAI-compatible
PublicAI	Open-source models	Gateway to open AI models

Configure via {TIER}_LLM_PROVIDER and {TIER}_LLM_MODEL environment variables (tiers: SMALL, MAIN, LARGE).

Partnerships & Research

Harmonica is developed in collaboration with the governance research community:

Metagov Interop First cohort participant in the Interoperable Deliberative Tools program

gov/acc Data collection tool for governance research in web3 communities

PublicAI Partnered for open-source AI model access

See also: Open Facilitation Library — our sister project developing reusable facilitation patterns, also part of Metagov Interop.

Project Structure

src/
├── app/                 # Next.js pages and API routes
│   ├── api/             # Backend endpoints
│   ├── chat/            # Participant chat interface
│   ├── create/          # Session creation flow
│   └── sessions/        # Session management
├── components/          # React components
├── lib/
│   ├── monica/          # RAG/LLM query system
│   ├── schema.ts        # Database schema
│   └── crossPollination.ts
└── db/migrations/       # Database migrations

Changelog

See CHANGELOG.md for a full list of changes.

Recent highlights:

• REST API v1 — public API with Bearer token auth for programmatic session management, plus API key management in the profile page
• harmonica-mcp — MCP server on npm enabling AI agents to create and query sessions
• harmonica-chat v2.0.0 — conversational session designer for Claude Code with guided design, project-aware creation, and full lifecycle management
• Facilitation evals — LLM-as-judge scoring on both synthetic and real production sessions
• Braintrust LLM observability — tracing across 10 operations with token usage, latency, and cost tracking

Contributing

We welcome contributions! Please see our Code of Conduct before participating.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support the Project

Harmonica is community-funded with no VC backing. If you find it useful, please consider supporting development:

License

AGPL-3.0

---

Built by the Harmonica team