Skitz

A terminal music agent built on Prime Agent. Sign in with your ChatGPT subscription, compose an editable score, render it, and make revisions that preserve protected tracks. No OpenAI API key is needed or used by the launcher.

Start

Requires Python 3.11+, Node.js 22.8+, npm and uv. The complete pinned Prime source is included in vendor/prime-agent; no separate Prime installation is required.

npm run setup
uv run skitz doctor
uv run skitz login
uv run skitz agent

login opens ChatGPT sign-in in your browser. Subscription eligibility, model availability and limits are controlled by OpenAI. Skitz stores its own OAuth session under ~/.skitz/agent, separately from Codex and Prime. It never imports their credentials. Set SKITZ_HOME to use another Skitz state directory.

Example request:

Compose four bars for soprano, alto, tenor and bass in G minor and 3/4. Protect the soprano. Validate, repair parallel fifths or octaves in the other voices, and render a score and audio. Preserve all revisions.

The initial model is Prime's pinned Codex default, gpt-5.5. Select another subscription model with uv run skitz agent --model <model-id> or SKITZ_MODEL. API-key providers and overrides are blocked. Prime's inherited help and TUI currently retain some upstream branding and provider menu entries; non-Codex provider calls are rejected in the runtime.

Music Tools

uv run skitz schema
uv run skitz create my-piece score.json --protect soprano
uv run skitz inspect my-piece
uv run skitz validate my-piece
uv run skitz analyze my-piece
uv run skitz patch my-piece patch.json
uv run skitz render my-piece --soundfont /path/to/GeneralUser-GS.sf2
uv run skitz verify my-piece --require-audio
uv run skitz export my-piece accepted-piece.zip

uv run skitz demo demo-piece creates a clearly labeled authored test fixture. uv run skitz import imported-piece source.abc imports supported ABC or uncompressed MusicXML. Unsupported constructs fail explicitly. Original Skitz scripts and documentation live in legacy/; original examples remain in Examples/.

Scores use exact quarter-note fractions, spelled pitches, stable event IDs, monophonic tracks, fixed meter/tempo, explicit rests, ties and basic articulations. The canonical JSON revision is the source of truth. Edits currently support pitch, tie and articulation changes within named measures. Arbitrary DAW sessions, polyphonic track import, changing tempo/meter maps and lossless LilyPond import are not supported in this first version.

Rendering

On macOS:

brew install lilypond fluid-synth

Provide a SoundFont you are licensed to use. See GeneralUser GS for a compatible option, its license and attribution. Skitz does not redistribute the SoundFont. Set SKITZ_SOUNDFONT or pass --soundfont. For only notation/MIDI, use --no-audio. For only source/MIDI/MusicXML, also use --no-engrave.

Each render records the revision, tool versions, SoundFont hash, synthesis settings and artifact hashes. PDF/WAV rendering currently requires the tested macOS restricted-worker backend. Other platforms fail closed for these operations; source/MIDI/MusicXML operations remain available where dependencies work. Rendering failures return nonzero status and retained diagnostics.

Use From Codex

Skitz exposes local MCP tools for creating projects, score inspection, validation, voice-leading analysis, bounded edits, revision comparison, rendering, rollback and export. Configure your MCP client to launch:

/absolute/path/to/skitz/.venv/bin/skitz mcp --workspace /absolute/path/to/music

For Codex, add this server to your own configuration:

[mcp_servers.skitz]
command = "/absolute/path/to/skitz/.venv/bin/skitz"
args = ["mcp", "--workspace", "/absolute/path/to/music"]

The MCP operations do not call a model or require authentication. Codex can use them through its own signed-in session. The repository also includes a discoverable Codex skill in .agents/skills/skitz/ and a Python-backed Prime skill in packages/skitz-music/. No global Codex settings are changed by installation.

Checks and Benchmarks

npm run check
uv run python evals/verify-editing.py work/editing-run --soundfont /path/to/font.sf2
uv run skitz bench --condition single-response \
  --prompt-file evals/bach-reproduction/paraphrased-prompt.txt --output work/bach-one-shot

Use a fresh output directory for each evaluation. Auggie's Bach Benchmark inspired the chorale tasks, notation feedback and voice-leading checks. The included prompt is an attributed paraphrase. Supply the original published prompt locally for an exact reproduction. Single-response, compiler-repair and structured Skitz runs are distinct conditions, not interchangeable results. See evaluation.

Prime's unrestricted agent kernel is not a security sandbox. Use trusted projects or an external restricted environment for the full agent. The notation/audio workers have separate restrictions; see architecture.

MIT license for Skitz. Prime and inherited pi notices are retained in full; see third-party notices and upstream provenance.