branch-tone

branch-tone

Hear your git context. Every repo has a voice. Every branch has a melody.

---

A CLI synthesizer that generates deterministic musical phrases from git branch names. Each repository gets its own harmonic identity — key, scale, timbre, pad shape — while each branch gets its own melodic identity — pattern, rhythm, envelope. Same inputs always produce the same sound.

Comes with a built-in interactive step sequencer featuring 10 classic drum breaks, a chromatic piano keyboard, and 7 synth presets inspired by jungle/liquid DnB hardware (Roland Juno-106, JP-8000, Korg M1).

Why?

Ever lose track of which terminal is on which branch? Now you can hear it.

One repo might be A# Lydian with a Swell pad shape. Another lands on E Mixolydian with a Pulse. Branches within each repo share that harmonic character but diverge in melody, rhythm, swing, and envelope — so main and feature/auth in the same repo sound like siblings, while the same branch in a different repo sounds like a stranger.

The result is ethereal, spaceship-like tones that ring out and overlap — inspired by the pad sounds of 90s jungle and liquid drum & bass.

Install

curl -sSL https://raw.githubusercontent.com/rmzi/branch-tone/main/install.sh | sh

Then register the Claude Code plugin:

branch-tone init                        # User scope (all projects)
branch-tone init --scope project        # Project scope (team-shared)

Or manually:

cargo install --git https://github.com/rmzi/branch-tone
branch-tone init

Quick Start

branch-tone                    # Play tone for current branch
branch-tone feature/auth       # Specific branch
branch-tone --dry-run          # Show parameters without playing

🎵 Repo: my-project | Branch: feature/auth [Arpeggio]
   Key: E Mixolydian | Octave: 1.5x | Shape: Swell
   Timbre: harmonic=0.13, 3rd=0.11
   Notes: ["494Hz", "881Hz", "623Hz"]
   Pattern: #4 | Envelope: Soft | Swing: 30%
   Stagger: [0.00, 0.02, 0.06, 0.06, 0.12]
   Spread: 0.92 | Duration: 600ms

Usage

# Sound modes
branch-tone --pad              # Warm subtractive chord
branch-tone --chorus           # BBD-style detuned layers
branch-tone --tremolo          # Volume wobble
branch-tone --bulldozer        # Layered pad (70%) + arp shimmer (30%)
branch-tone --spooky           # Thin sines, dark filter, eerie resonance

# Parameters
branch-tone --steps 5          # 5-note phrase (default: 3)
branch-tone --reverse          # Descending instead of ascending
branch-tone -d 800 -v 0.5     # Duration (ms) and volume (0.0–1.0)
branch-tone --repo my-project  # Explicit repo name

Environment Variables

Variable	Default	Effect
BRANCH_TONE_VOLUME	1.0	Global volume multiplier
BRANCH_TONE_TEMPO	1.0	Global duration multiplier

Interactive Step Sequencer

A real-time drum machine and piano keyboard that uses your repo's harmonic identity as its scale.

branch-tone player                    # Amen break at native BPM
branch-tone player --pattern 3        # Apache break
branch-tone player --bpm 140          # Custom BPM

 branch-tone player --- Amen @ 136 BPM --- [PLAYING]

    1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16
K   ●  ·  ·  ·  ●  ·  ·  ●  ·  ·  ●  ·  ·  ·  ·  ·
S   ·  ·  ·  ·  ●  ·  ·  ·  ·  ·  ●  ·  ·  ○  ·  ·
H   ●  ●  ●  ●  ●  ●  ●  ●  ●  ●  ●  ●  ●  ●  ●  ●
O   ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·  ·

                        ▲

 Piano: Oct 0 | Synth: Iceman | Shape: Swell

    W E   T Y U   O P
   A S D F G H J K L       [A# Lydian]

 [enter] toggle  [i] ghost  [</>] move  [^/v] row
 [1-0] pattern   [+/-] BPM  [space] play/pause  [q] quit
 [A-L] piano     [r] record  [z/x/c/v] rec K/S/H/O
 [[\]] octave   [,/.] synth  [;/'] pad shape  [tab] sustain

Drum grid — 16 steps, 4 rows (Kick, Snare, Hi-hat, Open hat). Toggle full hits (●) and ghost notes (○) with velocity cycling.

10 classic breaks: