ensemble

A Flutter app for developers who use AI tools: Codex, Claude Code, etc.

Uses local SQLite (~/.ensemble/ensemble.db) for local persistence. Uses Supabase to find other users who are active now. Logs users in with X.com/GitHub accounts.

Uses MCP protocol and subagents to:

• find other developers who use the same OS, frameworks, versions
• lets them know each other about their X.com handles
• lets them chat using https://github.com/flyerhq/flutter_chat_ui
• lets developers record hard-to-find solutions that were solved by their AI in more than medium effort in order to help developers who are using the same stack

Prerequisites

• Flutter 3.x
• Node.js 18+ (development only, for rebuilding MCP runtime)

Setup

1. Configure Supabase env (development)

cp mcp/.env.example mcp/.env
# edit mcp/.env with your real SUPABASE_URL and SUPABASE_ANON_KEY

2. Ensure MCP runtime is built (development)

cd mcp && npm ci && npm run build

3. Run the Flutter app

cd app && flutter run -d macos

The app auto-writes canonical MCP config at ./.mcp.json. ./.mcp.json is portable and secret-free:

• it runs ./mcp/bin/ensemble-mcp
• secrets remain in mcp/.env

Optional: you can still override values via CLI: --dart-define=SUPABASE_URL=... --dart-define=SUPABASE_ANON_KEY=...

For release distribution (including Mac App Store), prefer compile-time values: flutter build <platform> --release --dart-define=SUPABASE_URL=... --dart-define=SUPABASE_ANON_KEY=...

Sign in with your X account. Then use the Sync button in the Stack tab to publish your stack to Supabase.

Project structure

app/          Flutter macOS app
mcp/          MCP server (Node.js/TypeScript)
website/      Static landing page
supabase/     Edge functions + migrations

Landing Page

Static landing page is in website/.

• Run locally:
  • cd website
  • cp .env.example .env
  • npm install
  • npm run dev
• Configure waitlist frontend with env vars:
  • required: SUPABASE_URL
  • required: SUPABASE_ANON_KEY
  • optional: WEBSITE_YOLO_URL

Waitlist backend uses:

• Migration: supabase/migrations/023_waitlist_subscribers.sql
• Edge function: waitlist-subscribe

GitHub Pages deploy workflow:

• .github/workflows/website-pages.yml
• build env:
  • repo variable: SUPABASE_URL
  • repo secret: SUPABASE_ANON_KEY
  • repo variable (optional): WEBSITE_YOLO_URL

Packaging Notes

For end users, do not require npm at runtime. Package these artifacts:

• mcp/dist/*
• mcp/bin/ensemble-mcp (and mcp/bin/ensemble-mcp.cmd)
• mcp/node_modules/* (production-only deps, including better-sqlite3)
• optional bundled Node runtime at mcp/runtime/node/*

At runtime, MCP uses ./mcp/bin/ensemble-mcp, which prefers bundled Node and falls back to system node.

CI Release Artifacts

GitHub Actions workflow: .github/workflows/release-builds.yml

It builds release artifacts for:

• macOS
• Linux
• Windows

Each artifact includes:

• packaged Flutter app
• MCP runtime (mcp/dist, mcp/bin, mcp/node_modules)
• mcp/.env (from CI secrets if provided, otherwise copied from .env.example)
• bundled Node runtime in mcp/runtime/node
• helper scripts to register MCP with Claude/Codex

Set these repository secrets to preconfigure production builds:

• SUPABASE_URL
• SUPABASE_ANON_KEY

These same secrets are injected into Flutter build as --dart-define values, which is the standard way for sandboxed release apps to access non-secret config.

MCP Client Registration

Minimal-friction path:

• Claude Code: project-level .mcp.json is auto-written by the app. In Claude, run /mcp reload.
• Codex: one-time CLI registration is still needed (codex mcp add ...) unless already configured.

When adding MCP servers via CLI, pass Supabase values as server env (-e/--env), so MCP does not depend on reading .env from restricted filesystem locations.

Packaged artifacts include helper scripts:

• macOS/Linux: enable-mcp-claude.sh, enable-mcp-codex.sh
• Windows: enable-mcp-claude.cmd, enable-mcp-codex.cmd

These helper scripts read mcp/.env and pass SUPABASE_URL / SUPABASE_ANON_KEY to Claude/Codex MCP registration via -e/--env.

Troubleshooting

codex mcp remove ensemble
claude mcp remove ensemble -s user