retr0h/toneharness

Describe a guitar or bass sound, get a Line 6 Helix preset.

Built for agents, there to empower humans.

Every block on the device was measured through it, every claim in a rig names where it came from, and where nothing has been measured the tool says so. Point an agent at a checkout and tell it what you want to sound like.

A ToneSpec is what you want. A RigSpec is the gear that answers it. Both are YAML somebody can read, write, diff and send to a friend.

The specifications are OpenAPI, and every field carries its own description, so what a field may say and what gets refused is in the contract rather than in a page about it:

• tonespec.openapi.yaml, what somebody may ask for
• rigspec.openapi.yaml, what that resolves to

They are the only hand-authored formats here. The Go types and everything downstream are generated from them, and write-a-spec is what reads them back in prose, field by field.

schema: RigSpec
id: mike-dirnt
instrument: bass
chain:
  - role: amp
    gear: Ampeg SVT
    evidence:
      - kind: cited
        url: https://...

A rig names real gear, never Line 6 model identifiers. "Ampeg SVT" resolves through the gear map when it is built, so the file stays readable, stays correct when Line 6 rename a model, and compiles for whichever Helix you own rather than the one it was written on.

It goes the other way too. Pull a preset off the pedal and it comes back as a rig, so somebody else's sound becomes a file you can read, change and build again:

• "Export slot 12B as a rig so I can see what is in it."
• "Build this rig somebody sent me and put it on my pedal."

Every claim in a rig carries its source, which is what makes one worth sending. marketplace/ is where they live: a cited core that ships in the binary, and a community tier you load with --rigs. Its README says what the two tiers are and how to submit one. marketplace/core/examples/ holds one of each document with every optional field filled in. Those are what the tests pin and what to read when you want to see a field used, rather than rigs anybody plays.

Start your agent in a checkout and talk to it. Everything below is something to type.

• "Make my bass sound like Dookie."
• "I want a punk sound."
• "What did Geddy Lee actually play on Hemispheres?"

• "Put that on the pedal."
• "Find me an empty slot and put it there."
• "What is the pedal playing right now?"

HX Edit does not have to be running. You get the .hlx file too, if you want it there instead.

Nothing here can hear, so this is the loop: you play it, you say what is wrong.

• "Too woolly. Tighten the bottom up."
• "Closer, but I want the pick to cut more."
• "Turn it down a bit and measure it again."

• "What words can I use, and what does each one do?"
• "I asked for chunky and nothing moved. What should I have said?"

Nothing is refused over a word. Twenty-five are defined and only those move a control; the rest come back named, with the nearest ones that are.

• "Build me a rig for Justin Chancellor's Lateralus sound."
• "Do you have Tim Commerford, or do you have to research him?"
• "Why is this rig only medium confidence?"

Fifteen rigs ship with a citation behind every piece of gear. Anybody else gets researched, written up with sources, built to check it resolves, and opened as a pull request. If the evidence will not hold up you are told that instead, with what was searched, because a plausible rig looks like knowledge and is not.

• "Add Justin Chancellor to the bass corpus and measure what prog-metal earns."
• "Which genres can I aim at, and which are short of the threshold?"

It fetches the records, cuts the bass out, measures, and opens the pull request.

Two things it will tell you rather than let you find out: a genre needs eight records from three players before anything may aim at it, and a player whose records are measured but who has no rig contributes figures nothing can act on.

Your copies of the records stay on your disk.

Most of this needs no hardware. A corpus is audio files on disk, so adding records, measuring players, earning words and measuring a genre all run on a laptop with nothing plugged in. So does researching a rig, building one, and writing the preset.

Two things need the pedal, and one of those needs a lead from its output back to an input:

The second row is how the 19 swept amplifiers in resources/sweeps/ were measured, and they are committed, so nobody re-runs them. Without a loop you lose tuning a chain by measurement, which is the part that says whether a change did what it meant to. Everything else works.

The CLI is for an agent more than for a person, so the way to use toneharness is to point an agent at a checkout and say what you want to sound like. Each skill's own README says how to install and use it.

Each follows the Agent Skills format: a slim SKILL.md that routes, with the detail in reference files an agent reads only when the question calls for them. None of them writes down a list the tool can print. A list in a skill is right the day it is written and wrong after the next change, with nothing marking the moment.

A checkout, which is how the Quickstart above works: an agent reads the skills out of .claude/skills/ and runs the tree.

git clone https://github.com/retr0h/toneharness
cd toneharness
mise exec -- go run main.go --help

mise supplies the Go version .mise.toml declares. go run main.go compiles the tree every time, so what answers is the source rather than a binary that may be older than the branch, and --help is the command reference: no page here duplicates it.

There are no releases yet, so there is nothing to install. When there are, the installer and go install are the other two ways in:

curl -fsSL https://github.com/retr0h/toneharness/raw/main/install.sh | bash
go install github.com/retr0h/toneharness@latest

See CONTRIBUTING.md for prerequisites, setup, conventions and the pull request workflow.

The MIT License, see LICENSE.