harmony

harmony is a macOS desktop board for running Claude Code on your tickets. You add a ticket, drag it into In Progress, and harmony creates a git worktree, starts a supervised claude session in it, reviews the result, captures evidence that it works, and opens the pull request — with you watching every step and able to steer, comment, or take over at any point. It's a Kanban board where the cards implement themselves.

Download

Download the latest release — grab the harmony_*_aarch64.dmg from the Releases page (Apple Silicon Mac, macOS). See Install below for the one-time step to open an unsigned app.

After the first install, harmony updates itself: it checks for a new version on launch and offers a one-click "Install & restart", so you won't need to download a DMG again.

How it works

Each ticket moves through five columns, and harmony does something concrete at each one:

Column	What harmony does
Todo	Claude interviews you about the ticket until the spec is unambiguous — goal, acceptance criteria, relevant paths, constraints. You can edit the spec by hand at any time.
In Progress	Creates a git worktree off your repo's freshly-fetched default branch on a harmony/<key>-<slug> branch, then runs a live Claude session there. You can watch it, type into it, or answer its questions from the card. Your own working copy is never touched.
For Your Review	Runs a read-only Claude review of the branch, then a second, cheaper call judges its findings. You get the review, the diff, and (by default) a proof-of-work capture — screenshots or a video of the change actually working — so you can review the behaviour, not just the diff. Comment inline and send the feedback back for another pass.
In PR Review	Commits, pushes, and opens the PR with gh, with a generated description. From there it watches CI, and can fix red builds and resolve merge conflicts on its own.
Done	Squash-merges the PR, deletes the branch, and cleans up the worktree.

Nothing advances without a real signal: harmony injects HTTP hooks into each session, so it knows what Claude is actually doing rather than guessing. Every transition, and what may follow it, is generated from the state machine itself in docs/flow.md.

There's a longer walkthrough recording too — the Setup checklist, a fresh empty board, and a ticket crossing all five columns. (Both clips are the real app on a scratch profile with demo tickets, so no session transcripts or repository contents appear in them.)

A few things the columns don't show:

• Jira & GitHub, both ways. Syncs assigned Jira issues (via acli), drafts a spec from the issue, and writes status back on column moves. Opens a PR ready for review (via gh), and keeps the ticket and PR in step both directions — PR merged/closed → Done, reopened → In PR Review — with an "↗ PR" button and inline diff/checks.
• Nothing gets done twice. The autonomous steps — re-review on new commits, the self-correcting review judge → auto-fix, proof-of-work capture, CI-failure auto-fix, merge-conflict resolution and gated auto-merge — all run off the same pure state machine, and each is idempotent via a durable action log, so a restart never redoes work that already landed.
• Smart about loops & restarts. Re-work returns to the furthest stage it reached; trivial changes skip a full re-review/re-proof; and on relaunch finished sessions are recovered (not naively resumed).
• Supervised-first. Every autonomous step is opt-in and capped; you watch and steer in an embedded terminal, with proof, diff, review and PR tabs per ticket.

How much of this happens without you is your call — see Autonomy settings. Out of the box, nothing leaves your machine unless you move a card.

Requirements

• An Apple Silicon Mac (M-series), macOS.
• Claude Code — the claude command, on your PATH. harmony signs in with your own Claude Code login and stores no API key or token of its own; if you aren't logged in, your first session prompts you in its terminal.
• GitHub CLI (gh), authenticated — gh auth login. This is how harmony pushes, opens PRs, reads CI, and merges.
• git.
• A git repository with an origin remote. harmony works in worktrees of the repos you register; it needs origin because every ticket ends in a PR.

Optional:

• Atlassian CLI (acli), to pull the Jira issues assigned to you onto the board. Without it, harmony runs on local tickets.
• Node's npx, for proof-of-work capture (it drives a headless browser via Playwright, downloading that browser once on first use).
• Port 8787 free on localhost, for the hook server sessions report to.

The app checks all of this for you on first launch — and harmony doctor prints the same checklist in a terminal.

Install

1. Download the latest harmony_*_aarch64.dmg from the Releases page.

2. Open the DMG and drag harmony into Applications.

3. The app is unsigned, so macOS quarantines it and may report it as "damaged" — it isn't. Clear the quarantine flag once, then open it normally:

   xattr -cr /Applications/harmony.app

Your first ticket

1. Clear the Setup view. harmony opens on Setup until every required row is a ✓. Any row that isn't tells you exactly what to run (gh auth login, brew install gh, …), with a Re-check button beside it. Setup never blocks you — leave it and come back from the nav bar whenever you like.
2. Add a repository. The repo row has a Choose folder… picker. Pick the top folder of a git repo that has an origin remote; harmony refuses anything else, and says why.
3. Get a ticket onto the board, either way:
   • Connect Jira from the Setup view (install acli, then run acli jira auth login once — it opens a browser; no API key, no app registration) and harmony syncs the issues assigned to you, or
   • hit + New ticket, give it a title, and pick a repo.
4. Let Claude build the spec. It interviews you — awkward questions about scope, edge cases and acceptance criteria — and proposes a spec you accept, reject, or edit by hand.
5. Drag the card to In Progress. Claude starts working in the ticket's own worktree. Open the card to watch the session, answer its questions, or type at it directly.
6. Review what comes back. The card lands in For Your Review with a review, a diff, and proof of the change working. Leave inline comments and send them back for another pass, as many times as you like.
7. Ship it. Move the card to In PR Review and harmony pushes the branch and opens the PR. Once it's approved and green, move it to Done to squash-merge and clean up.

If something misbehaves, run harmony doctor; the app's own log is at ~/.harmony/harmony.log.

Autonomy settings

harmony spans a spectrum, from "supervise every step" to "wake me when the PR is merged". It's all in Settings, and every one of these is safe to change at any time.

Setting	Default	What it does
permission_mode	auto	How much Claude asks before acting in the worktree. plan proposes without changing anything; default asks per action; acceptEdits auto-approves edits and safe commands; auto is autonomous; bypassPermissions skips checks entirely (it's an isolated worktree, but still).
auto_review	on	Re-run the review automatically when a reviewed branch changes (feedback addressed, work resumed, a CI fix landed), so a review is never stale.
review_loop	off	When the review judge says changes are needed, fix them and re-review automatically — up to 3 rounds, then escalate to you.
proof	on	Once a change passes review, run a session that captures evidence it works — screenshots, video, or a grounded report — shown in the Proof tab and posted to the PR.
ci_autofix	on	When a PR's CI fails for a reason your branch caused, fix it and push — up to 3 attempts per PR.
conflict_resolve	on	When a PR conflicts with its base, merge the base in and resolve the conflicts — up to 3 attempts.
auto_merge	off	Squash-merge a PR by itself once it's approved and CI is green, then move the ticket to Done. Outward-facing and irreversible, so it stays off until you ask for it.
orchestrator	off	The coordinator: dispatches tickets, restarts crashed sessions, answers questions it can derive from the spec, and escalates the rest. This is what turns the board into a queue that drains itself.
max_concurrent	3	How many Claude sessions the orchestrator runs at once.

A conservative place to start: keep the defaults, and turn on review_loop once you trust the reviews. Leave auto_merge and orchestrator off until you've watched a few tickets land. Settings also has an idle-session cleanup toggle, automatic PR-description updates, and the (cheap) model harmony uses for its own background judgement calls.

What harmony touches on your machine

Everything harmony owns lives in ~/.harmony/:

Path	What's in it
harmony.db	SQLite: your repos, tickets, specs, sessions, comments, PR state.
harmony.log	Session and hook event log — the first place to look when something's odd.
worktrees/	One git worktree per ticket (worktrees/<repo>/<branch>), removed when the ticket is done.
proof/	Captured proof-of-work media, per ticket — deliberately outside your repo, so it can never be committed.
tools/	The shared capture toolchain (the Playwright browser cache), downloaded once and reused by every repo.

In your repos, harmony creates worktrees and branches prefixed harmony/, and commits and pushes on those branches only — never to your default branch, and never in your own working copy.

The one file it writes inside a worktree is .claude/settings.local.json, where it merges in four HTTP hooks (PreToolUse, PostToolUse, Stop, Notification) pointed at 127.0.0.1:8787. That's how it knows what a session is doing. The merge is additive and replaces only harmony's own previous entries, so anything else in that file survives — and it deliberately never writes your tracked .claude/settings.json, which usually holds your team's own hooks.

More

• CONTRIBUTING.md — building harmony from source, running the checks, cutting a release.
• docs/flow.md — the generated ticket lifecycle state machine.
• DESIGN.md — the decisions behind it.
• BACKLOG.md — what's next.
• LICENSE — MIT.