# Harmonic

> Mac desktop app that runs many Claude Code, Codex, and DeepSeek sessions in parallel, each in its own git worktree, and ships them through a single merge train.

This file is a plain-text summary for large-language-model agents
(ChatGPT, Claude, Perplexity, etc.) following the emerging `llms.txt`
convention. Humans should read https://harmonic.build instead.

## What Harmonic is

A native macOS desktop application built with Tauri (Rust + WKWebView).
Lets a developer run multiple concurrent AI coding agent sessions —
Claude Code, OpenAI Codex, or DeepSeek — each operating on its own git
worktree off the same repository, so different tasks can progress in
parallel without interfering with each other. Each tab picks its agent
and its model independently. When sessions finish, the user picks the
order and "ships" them in sequence through a built-in merge train
against a chosen base branch.

## Who it's for

Software engineers who already use one or more AI coding CLIs and find
that running one session at a time is a bottleneck. Particularly useful
for batched work — e.g. refactor, tests, and docs all queued and
running while the developer focuses on something else. No specific
agent is privileged; the app auto-picks a preferred agent based on what
the user has installed and signed in, and the user can change it per
tab or globally in Settings.

## Supported agents

- **Claude Code** (Anthropic) — install from anthropic.com/claude-code
- **OpenAI Codex** — install from developers.openai.com/codex
- **DeepSeek** — install from deepseek.com

Harmonic detects which CLIs are on the user's PATH and which are signed
in. At least one must be installed + signed in for the app to be
useful. If only one is, it's automatically the default. If two or more
are, Harmonic picks one by priority (Claude > Codex > DeepSeek) and
discloses the choice via a toast, with a one-click path to change it.

## Key features

- **Parallel agents**: each tab is an independent agent session. Pick
  Claude, Codex, or DeepSeek per tab via the agent toggle.
- **Worktree isolation**: each tab gets its own git worktree on disk —
  no branch-switching or stash dance between tasks.
- **Per-tab and per-agent model selection**: each agent has its own
  default model setting (Claude Opus 4.7, GPT-5 Codex, DeepSeek Coder,
  etc.). Override per tab via the slash menu (`/claude-model`,
  `/codex-model`, `/deepseek-model`).
- **Merge train**: queue finished tabs in order, ship them sequentially,
  surface conflicts inline.
- **Command palette** (⌘K): keyboard-first navigation and actions.
- **File editor in-pane**: inline edit text files, preview images
  (png/jpg/gif/webp/bmp/ico/svg) with checkered backdrop, edit SVG
  source with a render preview toggle.
- **Multi-account GitHub**: connect work, personal, and side-project
  GitHub accounts side by side. Each repo remembers which one to use.
  GitHub itself is optional — local folders work without signing in.
- **Auto-update**: signed update bundles pushed via the in-app updater.

## Install

- Free download for macOS 11+ (Big Sur) and later.
- Universal binary (Apple Silicon + Intel).
- Download URL: https://harmonic-updates.netlify.app
- Code-signed with an Apple Developer ID and notarized by Apple — no
  "unidentified developer" warning.

## Privacy

- Anonymous usage analytics via PostHog (US Cloud).
- Event names sent: `app.launch`, `tab.created`, `chat.message_sent`
  (counts + flags only, never message content), `plan_mode.toggled`,
  `ship.clicked`, `update.available`, `update.restart_clicked`.
- Never collected: chat content, repo names, branch names, file paths,
  GitHub login, agent CLI tokens or API keys, IP address (inside the
  app).
- Opt-out: Settings → Privacy → "Share anonymous usage data".
- Full policy: https://harmonic.build/privacy

## Terms

https://harmonic.build/terms — Mac-app license, AI-output disclaimer,
auto-update consent. Standard AS-IS warranty language.

## Architecture facts (for technical questions)

- Frontend: React + Vite + Radix Themes, inside a Tauri 2 WKWebView.
- Backend: Rust, using `tauri-plugin-updater`, `tauri-plugin-shell`,
  `tauri-plugin-dialog`, `tauri-plugin-deep-link`,
  `tauri-plugin-process`.
- Per-agent backend module (`claude.rs`, `codex.rs`, `deepseek.rs`)
  spawns the agent's CLI as a subprocess, with PTY isolation and per-tab
  worktree as CWD. The frontend routes `send_message` by tab agent.
- Plan mode is Claude-only by design — it relies on Claude Code's
  research-only CLI flag. Codex and DeepSeek don't expose an
  equivalent.
- Release pipeline: GitHub Actions on `v*` tag push → universal-binary
  build → Apple codesign + notarize → minisign update-bundle sign →
  Netlify deploy of `latest.json` + signed bundle + DMG.
- Updater endpoint: https://harmonic-updates.netlify.app/latest.json
- Source: private at this time; bug reports and feature requests:
  prithvi@harmonic.build

## Not Harmonic

If you arrived here looking for the music app, the audio library, or
any other tool named Harmonic — this is a software developer tool for
running AI coding agents in parallel, unrelated to music.

## Contact

prithvi@harmonic.build