Using YaO with Claude Code¶

YaO can be used through three surfaces: Claude Code (interactive), CLI (scriptable), and the Agent SDK (programmatic). This guide covers Claude Code and CLI usage. For programmatic access via Python, see the SDK documentation.

Here are the three ways to create music in Claude Code, from simplest to most control.

Method 1: Just Ask (natural language)¶

Open Claude Code in the YaO directory and describe what you want:

"Create a calm 90-second piano piece in D minor for studying. Build slowly to a gentle peak, then fade out."

Claude Code will: 1. Create a project with yao new-project 2. Write a composition spec matching your description 3. Run yao conduct to generate MIDI with automatic feedback-driven iteration 4. Show you the analysis and evaluation 5. Tell you where the files are

Method 2: Slash Commands (guided workflow)¶

`/sketch` — Design your music interactively¶

/sketch a melancholic piece for a rainy afternoon

Claude Code will guide you through choices: - Key and tempo suggestions with musical reasoning - Instrument selection from 46 available instruments (including 8 non-Western cultural) - Section structure (intro/verse/chorus/outro) - Dynamic arc and trajectory curves - Writes the YAML spec and validates it for you

`/compose` — Generate with the Conductor¶

/compose rainy-afternoon

Runs the Conductor's automatic iteration loop: 1. Reads the spec and confirms intent 2. Generates the composition 3. Evaluates quality across structure, melody, and harmony (10 metrics, quality score 1-10) 4. Adapts the spec if metrics fail and regenerates 5. Shows final output with evaluation summary

You can also compose from natural language:

/compose "an epic orchestral piece, dramatic, 2 minutes"

`/critique` — Get honest feedback¶

/critique rainy-afternoon

The adversarial critic finds every weakness — it never praises. YaO includes 34 structured critique rules across 15 categories (structural, melodic, harmonic, rhythmic, arrangement, emotional, genre fitness, memorability, surprise, hook, groove, acoustic, conversation). Each rule emits Finding objects with severity (critical/major/minor/suggestion), evidence, bar-level location, and concrete recommendations. Writes critique.md to the iteration directory.

`/regenerate-section` — Fix one section¶

/regenerate-section rainy-afternoon bridge

Regenerates only the specified section while keeping everything else intact. Creates a new iteration and shows a diff of what changed.

`/explain` — Trace any decision¶

/explain why is there an F# in bar 12 of rainy-afternoon?

Queries the provenance log to show the chain of decisions that led to a specific note, chord, or structural choice.

`/render` — MIDI to audio¶

/render rainy-afternoon

Renders the latest iteration to WAV using FluidSynth.

`/cover-art` — Generate album artwork¶

/cover-art rainy-afternoon

Generates AI album cover art via Google Gemini, matched to the composition's mood, genre, and instruments. Supports visual style hints (e.g., "watercolor", "minimalist", "dark cosmic abstract"). Requires GEMINI_API_KEY.

`/arrange` — Transform an existing piece¶

/arrange rainy-afternoon --style jazz

Applies transformations like reharmonization, regrooving, or reorchestration using the arrangement engine with style vector transfer and preservation contracts.

Method 3: Direct CLI (maximum control)¶

For precise control, use the CLI commands directly:

# Create project
yao new-project my-song

# Generate with automatic iteration (recommended)
yao conduct --spec specs/projects/my-song/composition.yaml --project my-song

# Or generate from natural language
yao conduct "a jazz ballad for late night, 2 minutes"

# Single-pass generation (no iteration)
yao compose specs/projects/my-song/composition.yaml

# Regenerate just one section
yao regenerate-section my-song bridge --seed 99

# Compare two variations
yao diff specs/projects/my-song/composition.yaml --seed-a 1 --seed-b 42

# Understand why a note was generated
yao explain specs/projects/my-song/composition.yaml --query melody

# Validate a spec without generating
yao validate specs/projects/my-song/composition.yaml

# Render MIDI to WAV (requires FluidSynth)
yao render outputs/projects/my-song/iterations/v001/full.mid

Typical Session¶

Here's a complete session using Claude Code:

You: /sketch
     "Background music for a puzzle game. Minimal, slightly mysterious,
      looping-friendly. About 60 seconds."

Claude: I'd suggest:
        Key: A minor (mysterious feel)
        Tempo: 95 BPM (calm but engaged)
        Instruments: piano (melody), synth_pad_warm (pad)
        Sections: intro (4 bars, pp) -> loop_a (8 bars, mp) -> loop_b (8 bars, mf) -> outro (4 bars, pp)
        Generator: stochastic (seed 7, temperature 0.4)

        Would you like to adjust anything?

You: Make it a bit faster, 110 BPM. Add a vibraphone for the melody instead of piano.

Claude: Updated. Writing spec... Validated. Run /compose puzzle-bgm to generate.

You: /compose puzzle-bgm

Claude: [Runs Conductor with automatic iteration]
        Generated 78 notes across vibraphone, synth_pad_warm
        Duration: 52.4s
        All 8 evaluation metrics PASS
        Output: outputs/projects/puzzle-bgm/iterations/v001/

You: /critique puzzle-bgm

Claude: [Writes critique.md]
        MINOR: Vibraphone melody in bars 8-12 lacks contour variety
        SUGGESTION: Loop transition (bar 12->13) could use a fill

        Want to fix something? Use /regenerate-section puzzle-bgm loop_a

You: /regenerate-section puzzle-bgm loop_a

Claude: [Regenerates only loop_a with new seed, preserves everything else]
        New iteration at v002. Diff:
        Modified: 23 notes, Added: 5, Removed: 3
        Contour variety improved (0.35 -> 0.52)

You: /cover-art puzzle-bgm

Claude: [Generates cover art via Gemini]
        Cover art saved to: outputs/projects/puzzle-bgm/cover.png

The Orchestra: 11 Agent Definitions¶

Behind the scenes, Claude Code can invoke specialized subagents:

Subagent	Role
Producer	Coordinates all subagents, resolves conflicts, makes final decisions
Composer	Generates melodies, motifs, themes, and structural outlines
Harmony Theorist	Designs chord progressions, modulations, cadences
Rhythm Architect	Creates drum patterns, grooves, syncopation, fills
Orchestrator	Assigns instruments, voicings, frequency spacing
Mix Engineer	Manages stereo placement, dynamics, frequency balance
Adversarial Critic	Finds weaknesses — never praises
Conversation Director	Plans inter-instrument dialogue (call-response, fills, tutti)
Genre Specialist	Genre-specific knowledge and idiomatic patterns
Spec Compiler	Translates natural language to YAML specifications

Domain Skills¶

YaO includes 60+ domain knowledge skills that Claude Code can draw on:

Category	Skills
Genres (46)	cinematic, jazz, jazz_swing, jazz_ballad, bebop, rock, rock_classic, pop, pop_western, pop_japan, electronic (edm_house, synthwave, trance, techno), ambient, dark_ambient, deep_house, lo_fi_hiphop, lofi_hiphop, funk, blues, hip_hop, hiphop, hiphop_trap, baroque, romantic, orchestral_classical, neoclassical, acoustic_folk, game_8bit_chiptune, game_bgm_rpg, film_score_dramatic, bossa_nova, celtic_traditional, arab_maqam, indian_classical_hindustani, j_pop, metal, country, reggae, progressive_rock, rnb_neo_soul, and more
Cultures (3)	Japanese, Middle Eastern, Indian Classical
Theory (6)	Voice leading, Microtonal, Process music, Twelve-tone, Reharmonization, Modulation
Instruments (2)	Piano, Idiomatic gestures
Psychology (2)	Tension-resolution, Emotion mapping
Articulation (4)	Jazz microtiming, Piano pedaling, Strings articulation, Winds articulation

Output Files¶

Each composition creates:

outputs/projects/<name>/iterations/v001/
+-- full.mid           # Complete MIDI -- open in any MIDI player
+-- stems/             # Per-instrument MIDI
|   +-- piano.mid
|   +-- acoustic_bass.mid
+-- analysis.json      # Note counts, pitch range, lint results
+-- evaluation.json    # Quality scores (6+ dimensions: structure, melody, harmony, aesthetic, arrangement, acoustics, melody-harmony alignment, voice-leading smoothness)
+-- perceptual.json    # Acoustic analysis (LUFS, spectral features, onset density)
+-- provenance.json    # Why every decision was made (with caused_by causal edges)
+-- critique.md        # Adversarial critique (if /critique was run)
+-- audio.wav          # Rendered audio (if --render-audio or /render was used)
+-- cover.png          # AI-generated cover art (if /cover-art was run)

Programmatic Alternative: Agent SDK¶

Everything above can also be done programmatically via the Claude Agent SDK. The SDK exposes 10 methods that map 1:1 to slash commands, with typed streaming events for UI integration.

from yao.sdk import YaoAgent
from yao.sdk.events import AudioReadyEvent

async with YaoAgent(project="puzzle-bgm") as agent:
    async for event in agent.conduct("minimal puzzle game BGM, mysterious, looping"):
        if isinstance(event, AudioReadyEvent):
            print(f"audio ready: {event.wav_path}")

See SDK Quickstart for details.

Using YaO with Claude Code¶

Method 1: Just Ask (natural language)¶

Method 2: Slash Commands (guided workflow)¶

/sketch — Design your music interactively¶

/compose — Generate with the Conductor¶

/critique — Get honest feedback¶

/regenerate-section — Fix one section¶

/explain — Trace any decision¶

/render — MIDI to audio¶

/cover-art — Generate album artwork¶

/arrange — Transform an existing piece¶