savannah-i-g/nanotracker-api-sdk

nanoTracker API SDK

Drive a live nanoTracker session from any AI coding agent, CLI, or script — no DevTools, no browser flags, no PWA-breaking workarounds.

---

What this is

A small, MIT-licensed harness that lets external programs read and write a live nanoTracker project running in a browser tab at .

The tracker exposes a JavaScript API (window.nanoTracker) with batched CRUD over patterns, samples, sequence layers, and song state. This SDK ships:

• a tiny local relay that bridges HTTP and the browser tab,
• an MCP server so any modern coding agent gets six tools for free,
• a CLI for shell scripts and humans,
• per-agent skill bundles mirroring the nanoTracker plugin-sdk layout,
• adapter snippets for nine MCP-aware coding tools,
• runnable end-to-end examples.

   you ──MCP / HTTP / CLI──>   relay (127.0.0.1:9311)   ──WS──>   nanoTracker tab
                                                              │
                                                              ↓
                                                window.nanoTracker

The page-side bridge that closes the loop ships with nanoTracker itself; this repo is the everything-else.

---

5-minute quickstart

You need Node 20+, a recent Chromium / Firefox / Safari, and a nanoTracker tab open at .

# 1. Clone + install
git clone https://github.com/savannah-i-g/nanotracker-api-sdk
cd nanotracker-api-sdk/tools
npm install

# 2. Start the relay
node relay.mjs
# → token written to ~/.nanotracker/relay-token, also printed to stderr

# 3. In the nanoTracker tab:
#    FILE > API…  →  Enable Local API
#                 →  Connect to local relay
#                 →  paste the token

# 4. Drive it
node ../tools/cli.mjs read getProjectSummary
node ../tools/cli.mjs execute '[{"op":"setBpm","value":140}]' '{"undoDescription":"first batch"}'

That’s the whole loop. Everything else in this repo is detail.

---