Codex Music

codex dev

Hot-reloading plugin workbench with inputs, diagnostics, logs, and export actions.

The workbench is shipped as the codex-plugin CLI from @codex-music/plugin-shell-kit. The longer plugin-shell-kit command remains an alias.

Usage

pnpm exec codex-plugin dev --cwd . --project plugin.config.json --open
# workbench: http://localhost:5173
# plugin Vite page: next available port

dev opens a workbench around your normal Vite app. Your plugin stays inside its own webview and keeps React, Vue, Svelte, or plain DOM hot module reload. The surrounding workbench reads plugin.config.json and the same ParamSchema used by the native shell.

The workbench itself uses @codex-music/site-ui, the same shadcn Base UI component package and theme as this website. Audio and MIDI controls are not a runner copy: both surfaces mount the shared AudioSessionControls component on top of AudioSessionController from the SDK.

The Node process watches the manifest and schema, serves configured sample files, relays build output, and accepts export commands. Changing UI source uses normal Vite HMR. Changing the schema or manifest refreshes the runner without throwing away the whole process.

Input and output

The toolbar only shows capabilities allowed by your manifest. Effects default to sample and microphone input. Instruments default to computer keyboard, Web MIDI, and chord pads. Available outputs are system audio, a captured monitor file, and MIDI where the plugin category allows it.

Browsers start audio on the first click. The runner keeps the page silent until you click Start audio, then requests only the permissions needed by the selected input. Microphone input is not routed to speakers, which avoids an accidental feedback loop.

Audio fixtures are served by the runner rather than copied into the UI bundle:

{
  "dev": {
    "inputs": ["sample", "microphone"],
    "fixtures": {
      "audio": [{ "name": "Guitar take", "file": "dev/fixtures/guitar.mp3" }]
    }
  }
}

Parameter inspector and host bridge

The inspector follows schema order, which is also the generated host parameter order. Every row shows the dotted path, display value, and normalized 0-1 value. You can drive a value from the inspector or the plugin UI and watch both surfaces stay synchronized.

The plugin webview receives a development implementation of window.codexHost. It supports the same ready, parameter, note, and state messages as the native shell. The optional bridge marker environment: "dev-runner" lets your UI identify this as a workbench instead of a DAW host.

Signal diagnostics

The right rail can show a time-domain scope, log-frequency spectrum / EQ view, and RMS / peak levels. These displays use real AnalyserNode data from the selected browser input.

The boundary is explicit: the compiled shared-WASM backend is not wired yet, so current diagnostics monitor browser input rather than processed plugin output. Parameter and host-message diagnostics are live. Processed output can replace the analyser source when createAudioEngine() gains its shared-WASM backend.

Logs

Plugin console calls, uncaught webview errors, bridge messages, schema reloads, runner events, and export output appear in one filterable log stream. This makes it possible to separate a UI binding problem from a schema or native build problem without switching between browser and terminal windows.

Export and package buttons

The toolbar exposes only targets listed in dev.exports:

  • Web builds the plugin-mode Vite bundle.
  • VST3, CLAP, and App build the UI, regenerate the native target, then run its CMake build.
  • Submit plugin writes a deterministic codex-plugin-package@1 source package under build/. The website upload step is not connected yet.

The package includes the manifest, schema, source and project assets, and content hashes. It excludes dependencies, generated output, environment files, signing keys, and VCS metadata. The future Submit Plugin endpoint can accept this exact object; the current runner keeps it local.

Flags

  • --cwd <dir> selects the plugin working directory. Defaults to ..
  • --project <file> selects the project manifest relative to --cwd. Defaults to plugin.config.json.
  • --port <n> serves the workbench on a different port. Defaults to 5173.
  • --host [address] binds to 0.0.0.0 by default for LAN testing, or to the explicit address provided.
  • --open opens the workbench in your default browser.

When the UI behaves, use an export button or run codex-plugin package --cwd . --project plugin.config.json directly in the terminal.