Build a machine
New machines come in as pull requests to lemus-dev/lemus. A coding agent such as Claude Code or Codex can do most of the work, from this page and the repo's CONTRIBUTING.md. A person makes the calls it can't, and the maintainers review and listen before a machine is released.
For your agent
Read https://lemusdev.org/contribute, then build a Lemus emulation of the <maker> <model> as it says. Stop and ask me at every gate.
- Method
- CONTRIBUTING.md
- Examples
- machines/tr909, machines/tb303
- Claims
- A GitHub issue, Machine: <Maker> <Model>
- Licence
- GNU AGPLv3, Signed-off-by on each commit, no CLA
- Needs
- A Mac; CMake 3.22+, Python 3.14, ngspice; a coding agent
- Questions
- lemus.discourse.group
Choosing a machine
A machine can be emulated to the standard of the released ones when four inputs exist. Without the first two it can't be; with all four public, it can be done without ever having the unit.
| Input | Where it comes from |
|---|---|
| Circuit | A service manual or schematic, data sheets, published analyses |
| Firmware, if it has a CPU | A ROM dump (a MAME set) and a CPU core (MAME's, BSD-3) |
| Custom chips | A data sheet, a community decode, or a decode from the firmware |
| Reference | Free recordings of real units, several to see the spread; for digital gear, an open bit-exact emulator run as an oracle |
Any machine without an open claim issue is open.
Who does what
The phases are CONTRIBUTING.md's. At a gate the agent stops until the person says go on.
| Step | The agent | The person |
|---|---|---|
| 0 Choose gate | Finds the schematic, ROM set, chip documents and free recordings. Proposes the target unit (revision, serial range) and the plugin name, and drafts the claim issue. | Picks the machine. Posts the claim. Waits for the maintainers to agree the target and the name; they assign the plugin code. |
| 1 Research | Downloads every source into the private folder, beside the clone. Writes sources.md and research.md. | Supplies the ROM images, and recordings of their own unit if they have one. |
| 2 Skeleton | Lays out machines/<id>/ from the 909's: driver, sleep, model version, artwork places, plugin name. | — |
| 3 Firmware | Ports MAME's CPU core, maps the board's I/O by running it, checks every procedure in the owner's manual. | — |
| 4 Circuit | Transcribes the schematic part by part, checks every netlist against ngspice, passes the service manual's checks. | — |
| 5 First playable gate | Draws the panel from a photo, adds keys, MIDI, state and power, builds the check set, compares against every real unit, writes improvements.md. Opens a draft pull request. | Installs it and plays it. Says what's wrong. Picks the first round. |
| Rounds gate | One kind per round, accuracy or CPU, with the whole check set before and after, and the numbers logged. | Picks each round, listens to its A/B scenes, decides any trade between sound and CPU. |
| Ship gate | Every service check passes, the CPU budget is met, the README has the numbers and the known differences. | Signs off the commits and marks the pull request ready. The maintainers review it, listen, merge and release it. |
Cost
Measured on this project, in Claude Code with Claude Opus 5.5. Codex hasn't been measured.
| Work | At API rates | On a Claude plan | The person |
|---|---|---|---|
| ro-drums-909, firmware and circuit: research to a calibrated release, two CPU rounds, a service view | about $1,600 | Max: about 40 % of its weekly allowance, for three weeks | 175 messages over 12 days |
| A circuit-only monosynth: research to first playable and its first accuracy rounds | about $500 | Max: about 40 % of one week's allowance | 16 messages over 3 days |
| The project's first four weeks: nine machines at different stages, the shared host, this site, three releases | about $4,400 | Ultra: about 45 % of four weeks' allowance; 55 % in the busiest week | — |
The plans' limits are weekly. In one measured week, 28 % of Ultra's allowance was about $710 at API rates, so a week of Ultra ($200 a month) is worth roughly $2,500 at API rates, a week of Max ($100) $1,250, and a week of Pro ($20) $250: on Pro, a machine like the 909 would take about six weeks of full allowances.
About half the cost is the agent rereading its own context. A new session for each phase or round costs less than one long session; improvements.md carries the state between them.
Rules
A pull request that breaks one of these is closed. The full list is in CONTRIBUTING.md.
- Nothing copyrighted in the repo. No ROMs, manuals, schematics, photos, recordings, vendor renders or logos. They stay in the private folder.
- Licences. MAME's CPU cores are BSD-3 and are ported with their notice. GPL projects are oracles only: run as separate programs, their source never read for this code.
- A machine is its folder. The pull request changes only machines/<id>/. A change to shared code is a pull request of its own.
- Free reference data. No bought sample sets. Every value in the docs names its source.
- The hardware, only. The panel is the machine's one view, and it has only the controls the unit has.
For agents
If a person has pointed you at this page to build a machine:
- Clone https://github.com/lemus-dev/lemus. Read CONTRIBUTING.md and README.md, then machines/tr909/, the example to copy.
- Check the machine has no open Machine: issue (gh issue list --repo lemus-dev/lemus --search "Machine:").
- Do phase 0 and stop. Show the person the choice note. Post nothing public, issue, pull request or forum post, without their go.
- Work only in machines/<id>/ and the private folder, ../private/. Never commit what belongs in the private folder.
- Stop at every gate: phase 0, phase 5, each round's pick and result, the pull request.
- Keep docs/improvements.md current, with numbers. It is how the next session and the reviewers know where the machine stands.
- Commit with git commit -s under the person's own git identity, with their consent. Never sign off in anyone else's name.
Submitting
One machine, one pull request, against main. Open it as a draft at the first playable machine, so the maintainers can follow it; mark it ready at the ship gate. The maintainers merge it, build the installers, write the machine's page here and announce the release. The machine's README and its page here name who built it, by name or handle. Rounds go on after release: a change to the sound then bumps the model version, so old sessions keep theirs.