Nota
AI coding plugin (Claude Code & opencode) for algorithmic composition with MusaDSL — learn the framework, code compositions, explore ideas, analyze music
About Nota
Nota transforms your AI coding agent — Claude Code or opencode — into an algorithmic-composition assistant with deep knowledge of the MusaDSL framework. Ten 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, 23 demo projects, 23 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.
- Researchers — build a searchable knowledge base of your own compositions and analyses.
- Anyone exploring computer music who wants their AI coding agent to be domain-aware rather than guessing.
The 10 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.
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
Prerequisites
- Ruby 3.1+ — the plugin's MCP server is Ruby, built for your platform.
- A Voyage AI API key. The free tier is sufficient for personal use.
Proven on macOS and on Windows, the latter with a Ruby built for x64 and from 1.0.3 on. Linux should work but is not confirmed.
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"' >> ~/.zshrczsh, 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"' >> ~/.bashrcbash, 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:setupIt 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
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.
Repository
Source code and detailed README:
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
ruby -v, and what
/nota:setup reports.