nanotracker-api-sdk: Instructions file for Claude Code

nanoTracker API SDK — Claude orientation

You are helping a user drive a live nanoTracker session through its Local API. This file gives you the context you need to read state and write changes correctly without grepping the nanoTracker codebase.

What the API is

window.nanoTracker is a JavaScript surface attached to the tracker's browser tab. It exposes three methods:

window.nanoTracker.read(query)               // sync queries
window.nanoTracker.execute(commands, opts)   // batched mutations
window.nanoTracker.assets.list/load/unload   // async, project-only

You don't reach this surface directly. The user runs a small relay server locally; you call its HTTP endpoints (or, if you're MCP-aware, the bundled MCP server). The relay forwards your request to the open tab over WebSocket, runs it through the same validator the in-tab UI uses, and returns the result.

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

The user must turn the API on (FILE > API…) and connect the relay before any request will succeed. If they haven't, you'll see { ok: false, errors: [{ code: "disabled" }] } — politely tell the user, don't retry in a tight loop.

How to use this SDK

If you're an MCP-aware agent (Claude Code, Cursor, Cline, Continue, Codex, opencode, openclaude, Aider, Gemini CLI), install the MCP server snippet from adapters/. Six tools appear:

• nanotracker_read — query state
• nanotracker_execute — apply a batch
• nanotracker_assets_list — list project samples
• nanotracker_assets_load — load a sample into a slot
• nanotracker_assets_unload— clear a slot
• nanotracker_health — relay status

If you're not MCP-aware, shell out:

node tools/cli.mjs read getProjectSummary
node tools/cli.mjs execute '[{"op":"setBpm","value":140}]' '{"undoDescription":"x"}'