Command line

claudius is one program with a subcommand per task. claudius --help lists them and claudius <command> --help shows the flags of one. The sample packs have a second program, claudius-packs, described in Sample packs.

Every command that fails prints Error: and the reason on stderr and exits with status 1.

Make a song

claudius make

Composes, arranges, mixes, masters and judges a new song, and writes it into a folder.

claudius make --genre deep_house --seed 7 --short

ears loaded in 3.8 s
Glass Garden — deep_house at 118 BPM in D minor, 52 bars (1:46)
  progression A: i7 VImaj7 iv7 v7
  progression B: VImaj7 v7 iv7 i7
  form: intro 8 | groove 8 | break 8 | build 4 | drop 16 | outro 8
  tracks: kick (synth kick), clap (synth clap), hat (hat cut from 'Silver Hi-Hat 04' (Apple Loops)), shaker (shaker cut from 'Ride With Me Shaker' (Apple Loops)), perc (perc cut from 'Latin Day Bongo 05' (Apple Loops)), bass (synth patch 'pluck_bass'), chords (synth patch 'keys'), pad (sampled string_ensemble (vsco2:strings)), lead (synth patch 'pluck'), crash (crash cut from 'Beautiful Memories Percussion 02' (Apple Loops)), riser (synth riser)
  master: -11.0 LUFS, true peak -1.0 dBTP (pre-master -10.3 LUFS); done in 11.4 s
  ears: 'house music' z +3.7 (closest confusion 'techno music' +3.9); production z +1.7 vs 'a low quality recording with hiss' +1.3; p_real 0.54
        sounds like: techno music, tech house music, house music, drum and bass music
  verdict: 86/100 (arc 0.94, genre 0.71, mix 0.93, production 0.59, theory 1.00). Fix first: dull 4-8 kHz: hats, claps and snare lack bite (presence -28.6 dB, healthy from -26); fizzy top end (air -16.2 dB, healthy up to -17); sounds more like 'techno music' than 'house music'
  wrote out/deep_house-glass-garden-7/song.mp3

The result depends on what is installed: the same genre and seed give the same song on any machine with the same packs and Apple Loops, and a different one, in its sounds and possibly its drum patterns, on a machine without them.

A seed from the clock is a number below one million, printed in the folder name, so you can make the same song again.

The song folder is <out>/<genre>-<title>-<seed>, for example out/deep_house-glass-garden-7, and holds:

Files and settings compares this with the folders claudius script and the studio write.

claudius script

Runs a script and renders the song it makes or edits.

claudius script song.rhai                       # a script that starts its own song
claudius script edit.rhai --on out/house-glass-haze-9
echo 'tempo(120); mute("lead");' | claudius script - --on out/house-glass-haze-9 --print

The folder has the same files as make writes. The script’s log goes to stderr: the song it started, the sounds each track resolved to (track hats: hh), and anything it printed with print() or debug(). A script that ends without a song fails:

Error: the script made no song (start it with song("house") or blank("house"))

Script errors come back with the line and position; Errors and limits lists them.

Error: Runtime error: tempo between 40 and 240 BPM (line 1, position 1)

claudius render

Renders a blueprint.json again, for example after you edited it by hand.

claudius mutate

Writes variations of a blueprint, each rendered in full, with what changed.

claudius mutate out/house-glass-haze-9/blueprint.json -n 4

Each variation goes into <blueprint folder>/mutations/<n>/ (or -o), and one line per variation reports the change and its verdict: 1: <what changed> -> <score> (<folder>). Unlike mutation in the studio, these mutations are not steered by the critic’s issues.

claudius evolve

Runs an evolutionary search: mutation and crossover over generations, each candidate judged on a preview of its build-up and first drop. Evolution and analysis explains the search.

claudius evolve --genre techno --seed 4 --start 2 --generations 2 --children 3 --preview-bars 16 --keep 0 --no-ears

evolving techno (2 start, 2 generations x 3 children, 16-bar previews, without ears)
  g0-0  90.5  Velvet Orbit
  g0-1  97.1  Hollow Harbor
  g1-0  97.1  from g0-1: tempo 128 -> 126 BPM
  g1-1  90.4  from g0-0: mix: bass -1.3 dB (now -1.3); form: outro now 12 bars
  g1-2  90.5  from g0-0: ride: synth voice parameter 0 -> 0.931
generation 1: best 97.1
  g2-0  97.1  from g0-1: form: peak drums main -> sparse; tempo 128 -> 130 BPM
  g2-1  97.1  from g0-1: form: groove drums main -> sparse; drums (main): nudged a hat hit by +0.25 beats
  g2-2  91.4  from g1-0: crossover: drums and form of one parent, harmony and parts of the other; form: break drums main -> sparse; form: build loses gap
generation 2: best 97.1
searched 8 candidates in 7 s; rendering the best 0 in full

A child that beats the best parent so far is marked with +. Every candidate goes into <out>/evolve-<genre>-<seed>/evolution.json (id, generation, parent, change, score, summary), and the best --keep are rendered in full into numbered folders next to it, with their history printed.

claudius remake

Analyses an audio file and writes a new song on its skeleton: tempo, key, swing, form, progressions, drum habits and bass style, with the genre’s sounds and mix. It prints the analysis (as analyze does) and the new song.

Listen and judge

claudius judge

Gives the critic’s verdict on any audio file. When the file has a project.json next to it (as make writes), the arrangement and theory checks run too; without one, only the meters on the master and the ears do.

claudius judge out/deep_house-glass-garden-7/song.wav --no-ears

out/deep_house-glass-garden-7/song.wav: 95/100 (arc 0.94, mix 0.93, theory 1.00). Fix first: dull 4-8 kHz: hats, claps and snare lack bite (presence -28.6 dB, healthy from -26); fizzy top end (air -16.2 dB, healthy up to -17)
  arc_correlation: 0.89
  band_air_db: -16.2
  band_low_db: -2.6
  band_lowmid_db: -5.5
  band_mid_db: -12.2
  band_presence_db: -28.6
  band_sub_db: -11.4
  bass_roots_on_changes: 1
  drop_minus_break_lu: 3.5
  lead_chord_tones_on_strong_beats: 1
  lead_in_key: 1
  lead_range_semitones: 12
  lead_stepwise: 0.63
  length_s: 106
  low_end_correlation: 1
  lra_lu: 3.73
  lufs: -10.98
  stereo_correlation: 0.86
  true_peak_db: -1.05
  voice_leading_chords: 1
  voice_leading_pad: 1.1
  - [0.44] dull 4-8 kHz: hats, claps and snare lack bite (presence -28.6 dB, healthy from -26) (band:presence-)
  - [0.13] fizzy top end (air -16.2 dB, healthy up to -17) (band:air+)

The critic and the ears explains every measure and score.

claudius analyze

Reads a song the way a producer does before remaking it.

claudius analyze out/deep_house-glass-garden-7/song.wav --genre deep_house

118.0 BPM (pulse clarity 0.55), Bb major (confidence 0.43), swing 0.50, 52 bars from 0.00 s
  progression A: iii7 Imaj7 vi7 vii  |  B: Imaj7 Imaj7  (1 bar(s) per chord)
  bar   0 +16  intro   energy 0.83  kick bass hats
  bar  16 +12  break   energy 0.30  kick hats
  bar  28 +24  drop    energy 1.00  kick bass hats
  kick  X.-xX.xxX.x.X.x-
  snare X.xXXxxxXxXxX-Xx
  hats  x-Xxx.X-xXXxx.XX
  bass style: offbeat

This is claudius reading its own D minor song: the tempo is exact and progression A has the song’s chords in their order (Dm7, B♭maj7, Gm7, Am), but named in B♭ major, and the break’s progression B came out as one chord where the song has four. Analysis of full mixes is approximate; the engineering page says where it goes wrong. In the step grids, X is a hit in almost every bar, x a common one, . a rare one and - none.

Make material

claudius chop

Cuts a recording into material: one bar loop per section it finds and a kick, clap and hat one-shot, saved as WAV files and added to the user library, where make and scripts find them.

claudius chop out/deep_house-glass-garden-7/song.wav --bars 2

chopped 3 loops and 3 one-shots (added to the user library):
  out/chops/song/01-intro-2bars.wav (118 BPM, 8 beats, key A#)
  out/chops/song/02-break-2bars.wav (118 BPM, 8 beats, key A#)
  out/chops/song/03-drop-2bars.wav (118 BPM, 8 beats, key A#)
  kick: out/chops/song/kick.wav
  clap: out/chops/song/clap.wav
  hat: out/chops/song/hat.wav

The analysis is printed first, as analyze prints it.

Apple Loops and your own samples shows how to use the chops.

claudius sounds

Renders every built-in synthesized sound to WAV files, so you can hear them: the 13 drum voices in drums/, the 20 synth presets playing a phrase in synth/, and five transition effects in fx/.

Information

$ claudius genres
deep_house   118-124 BPM  Deep house: softer four-on-the-floor, shuffled hats and shakers, minor 9th chords on electric piano and organ, a round syncopated bass, long warm reverbs
dnb          170-176 BPM  Drum and bass: 174 BPM two-step breakbeat (kick on 1 and the and-of-3, snares on 2 and 4 with ghost notes), a growling reese bass, atmospheric pads, long intro and breakdown
...

Run the studio and the server

These three commands run a session: one song with undo, renders and verdicts, which the studio window, browsers, assistants and the HTTP API share. They take the same session flags:

claudius studio

Opens the studio window. It first asks http://127.0.0.1:<port> what answers there:

• a claudius: the window opens on that session, says a claudius is already running on port 7878: opening the studio on it, and ignores the session flags;
• a claudius that asks for a token: it stops, since the window cannot send one, and says to open http://127.0.0.1:<port>/?token=<token> in a browser or to start another studio with --port;
• nothing: it starts a session and an HTTP server on 127.0.0.1 and --port (which also serves the web studio and MCP), then opens the window on it. A port taken by another program stops it with port 7878 is taken, by another claudius or another program (--port picks another).

A claudius built without the studio feature prints the address to open in a browser and keeps serving.

claudius serve

Runs the session and the HTTP server without a window: the web studio at /, the HTTP API under /api, and MCP at /mcp.

$ claudius serve
claudius at http://127.0.0.1:7878: web UI at /, API at /api, MCP at /mcp

It prints the address once the port is bound; a taken port stops it with port 7878 is taken, by another claudius or another program (--port picks another).

--public without --token makes a random token and prints how to use it:

$ claudius serve --public --port 7920
claudius at http://127.0.0.1:7920: web UI at /, API at /api, MCP at /mcp (token required)
shared with a new token: open http://127.0.0.1:7920/?token=<token> (through your tunnel, its address with ?token=<token>), or send Authorization: Bearer <token>. --token sets your own.

The token is new at every start; pass --token to keep one across restarts, as an assistant’s configuration needs. MCP tools shows the tunnel setup and the security model what each flag protects. --host with any address but loopback makes a token the same way, with or without --public: browsers on the network are refused by the host-name check, and the token keeps out programs that send Host: localhost.

--public, --host with an address other than loopback, or --files limits file access to ~/Music/claudius, claudius’ caches and the sound libraries, plus the --files folders; without any of them, commands read and write wherever you can. What a shared claudius may read and write has the details.

claudius mcp

Speaks MCP over stdin and stdout, for assistants that start claudius themselves (Claude Desktop, Claude Code, Cursor). It first asks the address in --url, or http://127.0.0.1:<port>, whether a claudius is running there:

• if one answers, every tool works on that session: the song open in your studio;
• if one answers but asks for a token that --token did not give (or gave wrong), it fails with Error: the claudius at <url> asks for a token: pass --token or set CLAUDIUS_TOKEN (a wrong one is refused too);
• if none answers and --url was given, it fails with Error: no claudius answers at <url>;
• otherwise it starts a session of its own and serves the web studio on --port, so you can open it to listen.

What it decided goes to stderr, which MCP clients show in their logs:

claudius mcp: driving the claudius app at http://127.0.0.1:7878

Set up and check

claudius setup

Downloads what does not ship with the program: the default sample packs and earshot’s listening models. On a terminal it asks before each download; elsewhere (and with --yes) it does not ask.

The prompt shows what is missing and how much it downloads: about 2.2 GB for the default packs, which take 1.2 GB on disk because several arrive as WAV and are converted to FLAC, and 785 MB for the models (the prompt says about 0.8 GB, or 1.1 GB with --tags). An interrupted pack download resumes where it stopped; a model file that was cut off downloads again from its start, and the files that finished are kept. After the models arrive, the first load spends about 30 s embedding earshot’s vocabulary once.

claudius doctor

Checks the installation and says what is missing.

$ claudius doctor
claudius 0.1.0 (macos aarch64)
  ok  web studio      ~/.local/share/claudius/web
  ok  sample packs    14 default packs (1.2 GB) in ~/Library/Application Support/claudius/packs
  ok  ears            models in ~/.cache/earshot-rs
  ok  Apple Loops     14096 loops and samples
  ok  ffmpeg          9.0.2 (writes song.mp3)
  ok  port 7878       free
  ..  Claude Desktop  not connected: `claudius connect claude-desktop`
  ..  Cursor          not connected: `claudius connect cursor`
  ..  statistics      off (`claudius telemetry` explains them)

Everything claudius needs is here.

ok is fine, -- counts as a problem, .. is optional. The port line says whether --port (or CLAUDIUS_PORT) is free, already serving claudius (claudius is running here, also for one that asks for a token), or taken by another program.

claudius connect

Adds claudius to an assistant, or removes it: its MCP configuration, and the skills that teach it claudius. MCP tools covers each client.

Every configuration file it edits keeps a .bak copy of the old one. Installing the skills replaces only claudius’ own skill folders (claudius-songs, claudius-remix, claudius-setup). An assistant reads its configuration when it starts, so connect ends by saying how to restart it: quit and reopen Claude Desktop, restart Cursor or reload its window, start a new Codex or Claude Code session.

claude-code runs the claude command, found on PATH or where its installers put it (~/.local/bin, ~/.claude/local, ~/.npm-global/bin, /opt/homebrew/bin, /usr/local/bin), and replaces a claudius Claude Code already has. The studio’s Connect an assistant does what connect does, and claudius doctor lists the assistants that are connected.

claudius update

claudius update             # downloads the latest release, and installs it after asking
claudius update --check     # only says whether there is a newer release
claudius update --auto off  # the studio stops looking for updates (on turns it back on)

It installs the latest release the way this claudius was installed: the Mac app, an AppImage, the install script’s programs, or the Windows installer, from the release’s file for this computer, checked against its SHA256SUMS. Installed with Homebrew, cargo, a .deb or .rpm, or built from source, it says how to update instead. --yes does not ask. Updates has the details.

claudius telemetry

claudius telemetry        # whether anonymous usage statistics are on, and an event exactly as it is sent
claudius telemetry on
claudius telemetry off

Anonymous usage statistics are off until you turn them on, here or when the studio’s tour asks. When they are on, claudius sends each kind of event at most once a day: which command started it, the version and the system, and where a setup or a panic failed. DO_NOT_TRACK=1, CLAUDIUS_TELEMETRY=0 and CI keep them off whatever the answer. Privacy and usage statistics lists every field and where they go.

claudius skills

claudius skills --out ~/my-project/.claude/skills

Writes the skills that teach an assistant claudius into a folder (claudius-skills by default): a folder with a SKILL.md for each, and a zip of each for the Claude apps. They are built into the binary, so they match it.