rnz

A CLI bridge that lets AI coding agents like Claude Code read, understand, and modify Renoise songs over UDP. Agents can analyze patterns, write notes, load samples, add DSP effects, automate parameters, and build full arrangements — all programmatically.

Also works as a standalone CLI for scripting and automating Renoise from the terminal.

Claude Code / Agent  →  rnz CLI (TypeScript)  ──JSON/UDP──▶  Renoise Lua Tool

Install

# Clone and build
git clone https://github.com/juliarvalenti/rnz.git
cd rnz
pnpm install
pnpm run build

# Install the Renoise tool (symlink)
ln -s "$(pwd)/renoise/com.rnz.Bridge.xrnx" \
  ~/Library/Preferences/Renoise/V3.5.0/Scripts/Tools/com.rnz.Bridge.xrnx

# Reload tools in Renoise: Tools > Reload All Tools

Usage

# Song info
rnz song
rnz tracks
rnz instruments
rnz sequence

# Transport
rnz play
rnz stop
rnz bpm 170

# Patterns
rnz pattern read 1 1              # dump as JSON
rnz pattern read 1 1 --compact    # non-empty lines only
rnz pattern clear 1 1
rnz pattern clone 1               # clone pattern at sequence position 1
rnz pattern copy-track 1 3 2 3    # copy track between patterns

# Write notes via stdin
echo '[{"line":1,"note":"C-4","instrument":"00"}]' | rnz pattern write 1 1

# Write chords (multi-column)
echo '[{"line":1,"columns":[
  {"note":"A-3","instrument":"00"},
  {"note":"C-4","instrument":"00"},
  {"note":"E-4","instrument":"00"}
]}]' | rnz pattern write 1 1

# Tracks
rnz track mute 3
rnz track unmute 3
rnz track solo 3

# Samples
rnz sample browse "/path/to/samples"
rnz sample load 2 "/path/to/kick.flac" --name "Kick"
rnz sample map 2 1 C-4             # map sample to a single note (drumkits)

# Instruments
rnz instrument show 1
rnz instrument modulations 1
rnz instrument add-mod 1 "Modulation/LFO" --target cutoff
rnz instrument filter 1 "LP Moog"
rnz instrument set-param 1 2 Frequency 0.27
rnz instrument set-prop 1 2 tempo_synced true

# Escape hatch — run arbitrary Lua in Renoise
rnz eval 'return renoise.song().transport.bpm'

# Pipe and script
rnz pattern read 1 1 | jq '.lines[] | select(.note != "---")'
for i in 1 2 3 4; do rnz track mute $i; sleep 1; done

How it works

Two pieces:

1. rnz — TypeScript CLI built with Commander. Sends JSON over TCP.
2. com.rnz.Bridge.xrnx — Renoise Lua tool that runs a TCP server on port 9876, receives JSON commands, and calls the Renoise Lua API.

Commands are colocated — each has a command.ts (CLI side) and handler.lua (Renoise side) in the same folder under src/commands/. Handlers are hot-reloaded on every request, so edits take effect immediately without restarting Renoise.

Development

pnpm run dev -- song          # run a command in dev mode
pnpm run dev:watch            # watch mode (rebuilds TS + Lua on change)
pnpm run build                # build CLI + Lua
pnpm run build:lua            # rebuild handlers.lua only
pnpm run build:docs           # regenerate docs/index.html

Adding a new command

1. Create src/commands/<name>/command.ts and src/commands/<name>/handler.lua
2. Register in src/cli.ts
3. Done — handler changes are picked up on the next CLI call

Docs

juliarvalenti.github.io/rnz

License

MIT