Docs

ModalJazz has two tools for scripts and AI agents. They change scores with no mouse and no key commands.

The mj tool

Make, read, change, and export scores in Terminal or in a script.

The compact score text

A short text form of the music. mj read shows it, and mj write writes it.

Agents (MCP)

Connect Claude Code, Claude Desktop, or another agent. The agent then reads and writes your scores.

Recipes

Steps for an agent: transcribe a PDF score, import MusicXML, and fix measures.

Install

The app has both tools in it. You do not install them one by one, and they update with the app.

Tool	Place in the app
`mj`	`/Applications/ModalJazz.app/Contents/MacOS/mj`
`mj-mcp`	`/Applications/ModalJazz.app/Contents/MacOS/mj-mcp`

To use mj in Terminal:

Move ModalJazz to your Applications folder, and open it once.
Choose ModalJazz > Install Command Line Tool…. The app makes the link /usr/local/bin/mj to the tool in the app. macOS can ask for your password.
Open a new Terminal window, and type mj help.

An agent does not need this link. Its settings give the full path of mj-mcp. See Agents (MCP).

Commands and score text

The tools take no key commands. They use two inputs:

: commands, as in the command line of the app. A measure range can come first: :5-8 transpose +P8. See the commands.
The compact score text for the notes: m5 P1.1: C5:q D5:q E5:h. See Score text.

Files

The tools open and save ModalJazz files (.mj) and MusicXML files (.musicxml, .xml, and .mxl). mj export also writes PDF, with all pages in one file, and SVG, with one file for each page.

Back up your scores

A score can be many hours of work. Back up every .mj file that you save. Keep a copy on a different disk or on a cloud service. ModalJazz does not make backups for you.

For the best results, keep your scores in a git repository, and commit after each work session. Git keeps the full history, so you can go back to an earlier version of a score. A .mj file is JSON text, so git diff shows what changed between two versions, line by line.

To start a repository in your scores folder and save the first version:

cd ~/Documents/Scores
git init
git add .
git commit -m "First version"

After each work session, save a new version:

git add .
git commit -m "Finish the bridge"

A commit stays on your Mac. To keep a copy on a different computer, push the repository to a hosting service, such as GitHub, or to a different disk.