A piano Claude Code
writes for, plays and teaches.
Piano plays a score as notes falling onto a keyboard, and then teaches it: it waits for you, tells you which bars went wrong, and raises the tempo each time you get a passage right. Its plugin gives Claude Code fifteen tools to write the piece you asked for, check it, keep it in your library and play it in the window in front of you.
› /piano:compose a short waltz in G, beginner, right hand writes
› validate_score checks
› save_score keeps
› play plays
› practise bars 1–4, right hand, from half speed teaches
A scripted session with the replies shortened. The tool names are the server’s own, read out of its source when this page was built. The server takes no file path and runs no command: save_score writes into ~/.piano/library and nowhere else.
Claude writes the music. You play it.
Most of what stands between a person and a piece they want to learn is the score: finding one at the right level, in a form the app can read. Here that is Claude Code’s job, and the app’s job is everything after it.
The app is a piano before it is a tool: everything the plugin can do, the window also does with its own controls, and it opens with scores to play before Claude has written one.
Six rules, each against a mistake
Binding in the sense that a feature breaking one is wrong even if it was asked for. Each names the mistake it prevents.
A grade names bars, never a percentage
“82%” tells nobody what to do next. “Bars 17 to 20, left hand, late” does, so the report is per bar and per section.
The server names no file and runs no command
Its transport takes a closed set of requests, so a score Claude writes can only ever be a score filed in your library.
One score format, with one owner
Every reader and writer goes through packages/score-format, and a check refuses a second copy, so the app never accepts a file the server rejects.
An easier level only takes notes away
A beginner arrangement derived from the score removes notes and never invents one, so what you learn is still the piece.
The sheet music never writes back
It is a view of the score, not an editor, so the file you practise is exactly the file that was written.
Nothing leaves the machine
Library, practice history and settings are local files. The one outbound request is the recorded piano, and only when you ask for it.
Three things a practice app usually gets wrong
Each is a reason somebody stops practising, and each is answered here by what the app does rather than by a setting.
It plays from the first second
A synthesised piano sounds the moment the app opens, matched in loudness and attack to the recorded one, so nothing waits on a download. The recorded piano is offered after, with its size stated first.
It teaches rather than scores
Each note comes back in time, early, late, wrong or missed, gathered per bar. The drill repeats the passage that needs it and moves the tempo by what you just played.
You can learn what you want to learn
Ask for a piece at your level and Claude writes it. For a piece still under copyright it offers an original in that style instead of a copy.
The notes fall onto the keys you press
The piano roll is drawn from the audio clock rather than the screen’s, so a note lands on its key at the moment it sounds, whatever the frame rate is doing.
- ✓See as far ahead as you like: the look-ahead goes from half a second to twelve.
- ✓Loop a passage by dragging across the roll, or
Lfrom the keyboard. - ✓Or read it: the same score as sheet music, one stave per hand, with a band that follows the playhead.
- ✓Transpose everything by up to two octaves, and hear or watch each part and each hand on its own.
- ✓Full screen shows nothing but the roll and the keyboard.
Three levels, and a drill that listens
A level is a way of playing the same piece, not a different piece. Where the score has its own arrangement for a level the app uses it; otherwise it derives one by taking notes away.
Beginner
The melody in one hand at two thirds tempo, with the score waiting for you.
Intermediate
Both hands a little under tempo, playing along rather than being waited for.
Advanced
The score as written, both hands, nothing waiting and a tight window.
What happens while you play
- ✓Wait for me stops the score at each note until you play it, so a beginner is never behind.
- ✓Graded per note: in time, early, late, wrong pitch or missed, plus anything extra, reported by bar and by section. With a MIDI keyboard, touch gets a line of its own.
- ✓Gentle, steady or strict: how wide the window is before a note counts as early or late.
- ✓The drill repeats a passage at a tempo that climbs after a clean repetition and drops back after a failed one, with either hand or both, the other hand accompanying or silent.
- ✓Latency calibration: the app clicks, you strike along, and it takes the median, per device, so your timing is judged and not your audio driver’s.
- ✓Your history is kept between sessions on your disk, and the footer saves it to a file or erases it.
Something to play within minutes of installing
A fresh install opens with Minuet in G, Ode to Joy and Prelude in C, bars 1 to 19: public domain, each with its own beginner, intermediate and advanced arrangement.
- ✓Every score Claude saves lands in
~/.piano/library, searchable by title, composer, level and tag. - ✓Drop a
.mid,.musicxmlor.mxlinto that folder and it is imported; drop one on the window and it opens. - ✓Correct a title, a composer or a level without touching the notes; a deleted piece goes to the system bin.
- ✓Save as MIDI exports the arrangement that is playing, for a DAW or another app.
Five pages, one per part of the app
Each has a page to link at, whether from a README, an issue or a search result.
Falling notes
How Piano draws a score as notes falling onto an on-screen keyboard, in time with the audio rather than the screen, and what the roll lets you do with a passage.
Read the page →Sheet music
The same score as engraved sheet music, one stave per hand, with a band that follows the playhead. A view for reading, never an editor.
Read the page →Practice
Wait mode, grading per note gathered by bar, three strictness settings, a drill whose tempo climbs, latency calibration and a history kept on your disk.
Read the page →The library
A local library that opens with three public-domain scores, imports MIDI and MusicXML, and a recorded grand piano downloaded only when you ask.
Read the page →The score format
A score is one JSON object: notes in ticks with a hand, a part and a finger, a tempo map, sections, and an arrangement per level. Validated by one package that owns it.
Read the page →What it will not become
Written down so they can be pointed at. Each one is somebody else’s product done well, and doing it here would make this one worse.
✗ A notation editor
The sheet view is for reading. Writing the score is Claude Code’s job, in the score format.
✗ Audio recording or export
Export MIDI and use a DAW, which will always do it better.
✗ Accounts, cloud storage or sync
The library, your progress and your settings stay on your own disk.
✗ Other instruments
It is a piano, and every screen assumes one.
✗ Listening through a microphone
Input is a MIDI keyboard or the computer keys, which say exactly what was played.
✗ Transcribing recordings or PDFs
MP3, YouTube and scanned sheet music are not scores, and guessing at them teaches the wrong notes.
✗ Copyrighted scores
What ships is public domain, with its source and licence recorded in the file.
✗ A web or mobile version
It is a desktop app, where MIDI and low latency are.
Two lines in Claude Code, and the app
The plugin brings the MCP server and the commands. It needs only Node 20.11 or later, and the tools that write, check and keep scores work before the app is installed.
The plugin, in Claude Code
/plugin marketplace add alegauss/piano
/plugin install piano@pianoThe app, for your computer
The release page has an installer for Windows, a disk image for each kind of Mac, and an AppImage for Linux. They are not signed yet, so your system warns the first time; the release notes show what it says and how to get past it.