Nota — AI coding plugin for algorithmic composition with MusaDSL

Two minutes of Nota

A short piece in the manner of the young Mozart, from the musical intention to the sounding result, composed with MusaDSL and Nota. The video has sound — unmute it.

About Nota

Nota transforms your AI coding agent — Claude Code or opencode — into an algorithmic-composition assistant with deep knowledge of the MusaDSL framework. Eleven interactive skills cover the entire creative process — from understanding the framework, through brainstorming ideas, to writing verified code, analyzing the results, and consolidating best practices.

Everything is backed by a knowledge base with MusaDSL documentation, API reference, the demo projects, built-in composition best practices, and — optionally — your own compositions and their musical analyses.

Say "hello musa" inside Claude Code (or just ask for a capabilities overview in opencode) to get a welcome tour.

Who is it for?

Composers learning MusaDSL — ask questions in natural language, get sourced answers.
Working algorithmic composers — describe a musical intention, get verified code.
Artist-researchers — think, write, listen and reflect in one place, so that what each piece teaches you gets written down as it happens, in your own terms, and the next piece starts from it.
Anyone exploring computer music who wants their AI coding agent to be domain-aware rather than guessing.

The 11 Skills

Core composition workflow

`/nota:explain`

Semantic search over MusaDSL. Ask about any concept and get an accurate, sourced answer with relevant documentation, API details, and working code examples retrieved from the knowledge base.

`/nota:think`

Creative thinking and ideation. Generates ideas for new compositions or explores new directions for existing ones. Draws from the inspiration framework, your previous analyses, the MusaDSL knowledge base, and the open web to connect ideas to composers, techniques and traditions with accurate references.

`/nota:code`

Composition coding. Translates musical intentions into working MusaDSL Ruby code. Verifies every method call against the API, draws from demo examples and your own indexed works, and always proposes the approach before writing.

`/nota:index`

Works indexing. Add your composition projects so Claude can reference them. All .rb and .md files are indexed recursively; once indexed, your works appear in search results and inform every other skill.

`/nota:analyze`

Musical analysis. Reads your code, interprets it musically, and produces a detailed structured analysis across 10 default dimensions. The analysis is stored as searchable knowledge, enriching every future /nota:think, /nota:code and /nota:explain session.

`/nota:best-practices`

Best practices management. Extract recurring patterns from your analyses into reusable best practices, or add them manually. /nota:code automatically consults them when writing new code, so your consolidated patterns are applied consistently.

Framework customization

`/nota:inspiration-framework`

View, modify or reset the inspiration framework that guides /nota:think. The default has 9 dimensions: Structure, Time, Pitch, Algorithm, Texture, Instrumentation, Reference, Dialogue, Constraint. Add your own dimensions or rewrite them entirely.

`/nota:analysis-framework`

View, modify or reset the analysis framework that guides /nota:analyze. The default has 10 dimensions: Formal Structure, Harmonic and Modal Language, Rhythmic and Temporal Strategy, Generative Strategy, Texture and Instrumentation, Idiomatic Usage, Relation to Other Artists, Notable Technical Patterns, Coding Best Practices, Conclusion. Customize per your compositional priorities.

Onboarding & operations

`/nota:hello`

Welcome and capabilities overview. Start here when interacting with Nota for the first time, or trigger it by saying "hello musa".

`/nota:setup`

Plugin configuration and troubleshooting. Verifies the Voyage AI API key, checks knowledge base download, confirms MCP server connectivity. Run this after install.

`/nota:license`

Nota's terms of use in three lines, and the exact text on request: what you may do with the plugin, and who owns the music, code and analyses you make with it.

In both Claude Code and opencode, you can invoke any skill with /nota:<skill> (e.g. /nota:explain), or simply describe your task and the model picks the right skill automatically (model-invoked — no slash command needed).

Knowledge bases

Nota's depth comes from two SQLite-vec databases queried with Voyage AI embeddings, which let every skill ground its output in concrete sources rather than the model's general knowledge.

Database	Scope	Storage
`knowledge.db`	MusaDSL documentation, API reference, 23 demo projects, 23 built-in composition best practices.	Downloaded to `~/.config/nota/`, refreshed when a new index is published.
`private.db`	Your indexed compositions (added with `/nota:index`), their musical analyses (created with `/nota:analyze`), and your custom best practices (`/nota:best-practices`). Search across them as easily as the public docs.	Local, in `~/.config/nota/`. Never leaves your machine.

Both databases use sqlite-vec for vector storage and Voyage AI for high-quality multilingual code-aware embeddings. The plugin's MCP server exposes a search tool that every skill consults transparently.

Workflow loop

Skills feed into each other. Used together, they form a virtuous loop where each composition enriches the assistant for the next one:

/nota:think → /nota:code → /nota:index → /nota:analyze → /nota:best-practices → back to /nota:think

Think — explore ideas across the inspiration dimensions, informed by your past work.
Code — turn the idea into verified MusaDSL code, consulting docs, demos and best practices.
Index — add the finished composition to your private knowledge base.
Analyze — generate a structured musical analysis of the work.
Best-practices — extract recurring patterns from your analyses into reusable practices.
Think again — now your future ideation draws from a richer corpus.

The more you compose and analyze, the more domain-aware Nota becomes for your specific style.

Getting Started

Requisites

Ruby 3.1+ — the knowledge base server is Ruby.
MusaDSL — the framework Nota assists with. Nota reads the copy you install for your own work.
A Voyage AI API key, for the embeddings. The free tier is enough for personal use.
macOS or Windows — on Windows on ARM, use an x64 Ruby, see Troubleshooting. Linux: to be tested.

Install

1. Add your API key

Nota's MCP server runs as a subprocess of your coding agent, and inherits the environment of whatever launched it. Set the key in two places: the session you have open now, and every session from now on.

# this session
export VOYAGE_API_KEY="your-key-here"

# every session from now on
echo 'export VOYAGE_API_KEY="your-key-here"' >> ~/.zshrc

zsh, the default on macOS. Under bash, the second line goes to ~/.bash_profile.

# this session
export VOYAGE_API_KEY="your-key-here"

# every session from now on
echo 'export VOYAGE_API_KEY="your-key-here"' >> ~/.bashrc

bash, the usual default. Under zsh, the second line goes to ~/.zshrc.

PowerShell

# this session
$env:VOYAGE_API_KEY = 'your-key-here'

# every session from now on
[Environment]::SetEnvironmentVariable('VOYAGE_API_KEY', 'your-key-here', 'User')

cmd

:: this session
set VOYAGE_API_KEY=your-key-here

:: every session from now on
setx VOYAGE_API_KEY "your-key-here"

2. Install the plugin

Start Claude Code from the terminal where you set the key:
```
claude
```

Add the yeste.studio marketplace:

/plugin marketplace add javier-sy/claude-plugins

Install the plugin:
```
/plugin install nota@yeste.studio
```
Finish the setup:
```
/nota:setup
```
It reports what is still missing and installs it — about 30 MB, once. Your own Ruby is not touched.
Leave Claude Code. The knowledge base server only starts with a new session:
```
/exit
```
Come back to the same conversation:
```
claude --continue
```

On hold

Nota is available for Claude Code only. The opencode channel is on hold: npm serves an old release under the previous name (nota-plugin-for-opencode 0.11.1), from before most of what Nota does now.

First questions

Say "hello musa" for the welcome tour, or go straight to /nota:explain how does the sequencer work?

What gets downloaded

Everything lands in ~/.config/nota/, and /nota:setup brings all of it: the Ruby dependencies the knowledge base runs on, the 200 KB sqlite-vec extension, and the latest knowledge.db — MusaDSL documentation, API reference, demos and best practices, pre-indexed with their Voyage embeddings. Your private.db is created empty the first time you index a work of your own; nothing private leaves your machine.

License

Free of charge. Install it and use it, on as many machines as you like, for anything — including professional and commercial work.
What you make with Nota is yours. Code, scores, recordings, analyses: no condition on how you license, publish, perform or sell them, and nothing owed in return, whether you wrote it or the assistant did.
The source is not open. Nota is licensed to be used, not copied, modified or redistributed. The terms ship with the plugin, in its LICENSE file.
MusaDSL is free software (LGPL 3.0), and so is the knowledge base. Only the assistant is licensed differently.

/nota:license shows these terms inside your session, and the full text on request. What binds is that text, not the summary.

Repository

Detailed README and the knowledge base releases: javier-sy/nota

Troubleshooting

Symptom	Likely cause / fix
`/nota:setup` says Voyage key missing	The key is not in the environment your agent was launched from. Set it, then reopen Claude Code or opencode from a terminal that has it.
Knowledge base did not download	Check internet connectivity; `/nota:setup` retries the download.
Search returns empty results	The plugin may not have indexed your local works yet — run `/nota:index` on the project root.
`Could not find mcp-…` / `sqlite3-…` in locally installed gems	The knowledge base server says this and stops, which is what it is meant to do: the gems are installed by `/nota:setup`, not on startup. Run it, then start Claude Code again — `claude --continue` keeps the conversation. Reloading plugins does not restart an MCP server.
The session says the platform is not supported	Windows on ARM: neither `sqlite3` nor `sqlite-vec` publishes a build for it. Install a Ruby built for x64 — Windows runs it under emulation — and set `NOTA_RUBY` to its `ruby.exe` so your other Ruby work keeps the interpreter you have.
The sqlite-vec extension did not download	The knowledge base cannot open without it. Check internet connectivity and reopen the session; `/nota:setup` reports the path it resolved and retries.
`Missing environment variables: HOME`, and no Nota tools available	Nota 1.0.1 and earlier on Windows. Update the plugin — 1.0.2 no longer asks the editor where your home directory is.
MCP server connection failing	Run `/nota:setup`: it reports the Ruby side, the key, the extension and both databases, and names which one is missing.

If installation fails on your platform, please tell me — especially on Linux or Windows. Open an issue at javier-sy/nota with your operating system, the output of ruby -v, and what /nota:setup reports.

More from the MusaDSL ecosystem

MusaDSL — Ruby framework for algorithmic sound and musical composition.
MusaLCE — live coding for MusaDSL: a toolkit to build your own Live Coding environment targeting any MIDI/OSC/other destination, or ready-made for Bitwig Studio and Ableton Live.
Nota — AI coding plugin (Claude Code & opencode) for MusaDSL composition assistance.
Pulso — elgato Stream Deck control for music DAWs (Bitwig today; Ableton planned), with MusaLCE Surface integration (upcoming).

Author

Nota is created and maintained by yeste.studio, exploring the intersection of sound, music, technology, and algorithmic composition. It is part of the MusaDSL family of projects.

Free of charge · Proprietary

Issues and knowledge base releases on GitHub.