BeatFlow Skill

Compose complete, editable multi-track MIDI with Codex.

BeatFlow turns a musical brief into an explicit Python composition plan, validates its timing and musical relationships, realizes functional pitches and chord voicings, and exports deterministic Standard MIDI. The result stays inspectable and editable: every onset, duration, role, phrase, and arrangement decision is represented as data rather than hidden inside an audio model.

BeatFlow 2.0 requires Codex and Python 3.10 or newer. It produces symbolic MIDI, Composition JSON, Project JSON, and diagnostic reports; the included MP3 files are listening previews.

Listen

The examples are output snapshots, not templates or source material used by the engine.

Why BeatFlow

• Codex composes; code keeps relationships exact. Codex makes the open musical decisions while the engine handles rational timing, pitch realization, voicing, validation, and MIDI serialization.
• The representation is editable. A small Python DSL compiles to strict Composition 1.1 JSON and an internal Project before MIDI rendering.
• Gestures preserve identity and exact time. Reusable subdivision cells express attacks, same-pitch repetitions, holds, rests, and selected dyads or triads before deterministic expansion to literal note events.
• Diagnostics test intent, not genre conformity. Phrase, arrival, meter, role, silence, repetition, and arrangement checks compare the written plan with the realized events.
• Reference evidence stays descriptive. MIDI profiles, local benchmark ranges, and isolation packs help locate timing, phrasing, density, and role problems without turning reference songs into templates or quality scores.
• The engine stays style-neutral. Genre affects the authored harmony, rhythm, form, instrumentation, and phrasing rather than selecting an engine template.

Pipeline

musical brief
    -> Codex-authored Python composition plan
    -> strict Composition 1.1
    -> validation and advisory diagnostics
    -> deterministic pitch, voicing, and arrangement compilation
    -> Standard MIDI + Composition, Project, and report JSON
    -> optional profile, reference benchmark, and causal audition pack
    -> listening selection and revision

Composition 1.1 supports:

• exact rational positions and literal durations, including tuplets;
• meter-aware bar and tactus addressing;
• functional, relative, or absolute pitch targets;
• reusable exact-grid foreground gestures with monophonic and selective polyphonic attacks;
• designed chord top lines and deterministic voice leading;
• reusable sections with occurrence-level arrangement changes;
• instrument contracts and general musical roles;
• phrase grouping, stages, focus, arrivals, silence, and role interactions;
• diagnostics for timing, continuity, completion, density, repetition, masking, and structural non-chord tones.

Install

Skills CLI

With Node.js available:

npx skills add the0cp/beatflow-skill --skill beatflow-skill --global --agent codex --yes

Run the installation smoke test from the installed skill directory:

python scripts/run.py self-check

GitHub CLI

With GitHub CLI 2.90 or newer:

gh skill install the0cp/beatflow-skill beatflow-skill --agent codex --scope user

Codex skill installer

From a Codex conversation:

$skill-installer install https://github.com/the0cp/beatflow-skill/tree/master/skills/beatflow-skill

The launcher creates an isolated cached runtime and installs the pinned packages in requirements.txt. Set BEATFLOW_CACHE_DIR to choose another cache location.

Use

Open a workspace and give Codex a concrete brief:

Use $beatflow-skill to compose a 2-3 minute neo-soul piece in 4/4 at about
88 BPM. Use Rhodes voicings with a designed top-note line, an independent
electric bass, restrained drums, and deliberate melodic space. Validate the
composition, revise structural problems, and export MIDI plus Composition,
Project, and diagnostic JSON.

BeatFlow writes the composition script and generated files in the workspace, not in the installed skill directory.

A foreground gesture can mix repeated single notes with chordal punctuation without calculating every onset separately:

from beatflow_core.composer import (
    beat, chord, chord_hit, gesture, hit, hold, rest, same
)

hook = gesture(
    beat(1, 2),
    [
        hit(chord(3)),
        same(),
        hold(),
        rest(),
        chord_hit(notes=2, top_target=chord(5)),
        rest(),
    ],
    motif="hook",
)
lead.place(hook, beat(0))
lead.place(hook, beat(4))

same() is a new attack at the preceding pitch; hold() extends the active sound. chord_hit() requires a foreground track that is not monophonic.

To run a trusted composition script directly from the repository checkout:

python skills/beatflow-skill/scripts/run.py compose song.py song.mid \
  --composition-output song.composition.json \
  --project-output song.project.json \
  --report song.report.json

Useful commands:

python skills/beatflow-skill/scripts/run.py --version
python skills/beatflow-skill/scripts/run.py schema --output composition.schema.json
python skills/beatflow-skill/scripts/run.py validate song.composition.json
python skills/beatflow-skill/scripts/run.py diagnose song.composition.json
python skills/beatflow-skill/scripts/run.py inspect song.mid
python skills/beatflow-skill/scripts/run.py profile path/to/reference-midi --output references.profile.json
python skills/beatflow-skill/scripts/run.py benchmark song.mid path/to/reference-midi --output benchmark.json
python skills/beatflow-skill/scripts/run.py audition song.mid audition
python skills/beatflow-skill/scripts/run.py self-check

Reference files are user-supplied local inputs. BeatFlow does not bundle, redistribute, train on, or copy music from a reference collection. Profile and benchmark output is descriptive evidence; listening remains the selection step. The audition pack isolates foreground, foreground rhythm, accompaniment, and rhythm-section behavior without requiring an audio renderer.

Upgrade

Skills CLI installation:

npx skills update beatflow-skill --global --yes

GitHub CLI installation:

gh skill update beatflow-skill

For a Codex skill-installer installation, run the installation prompt again.

Develop and test

macOS or Linux:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .
.venv/bin/python -m unittest discover -s tests -v
python3 skills/beatflow-skill/scripts/run.py self-check

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
python skills\beatflow-skill\scripts\run.py self-check

The tests cover exact timing, models, validation, diagnostics, compilation, arrangement occurrences, MIDI rendering, inspection, reference profiles, benchmarks, audition isolation, and controller output.

Repository layout

• skills/beatflow-skill/SKILL.md: composition and revision workflow for Codex
• skills/beatflow-skill/agents/openai.yaml: skill interface metadata
• skills/beatflow-skill/scripts/beatflow_core: DSL, models, compiler, validators, diagnostics, and MIDI renderer
• skills/beatflow-skill/scripts/run.py: dependency-aware launcher
• skills/beatflow-skill/references: format, architecture, musical guidance, and research
• examples: listening snapshots used to evaluate the generated arrangements
• tests: unit and end-to-end tests

License

GPL-3.0-only. See LICENSE.