Skip to content

Work with a coding agent

View Markdown
For agents

Give your agent this page’s Markdown link, or choose a collection.

Any coding agent that can edit local files and run shell commands can work on a DAWN song. Give it the project directory and an outcome, then use the same check-and-render loop you would use yourself.

Install DAWN using the first-song prerequisites, then run dawn init in a new song folder. It creates AGENTS.md with the current project workflow and a CLAUDE.md that refers to it. Existing notes outside the DAWN-owned markers are preserved.

The agent should read AGENTS.md, song.ts, relevant track files and .dawn/sdk/v1.ts before editing. The SDK is a dependency-free TypeScript file with the exact types, defaults and JSDoc examples for the version this project uses.

Add a quieter piano answer in the chorus. Keep the existing bass and drum parts. Run the project check, then render a new WAV and a MIDI file.

Keep a copy or a commit of the project before a substantial edit. DAWN evaluates song source in a sealed engine with no file, network or process access, but a coding agent works with your own authority, so only run agents you trust.

  1. Edit song.ts or tracks/<slug>/track.ts.
  2. Run dawn check --json and fix the reported problems.
  3. Run dawn render review.wav --measure and inspect the result.
  4. Run dawn render review.mid when you need an editable MIDI export.

dawn check exits zero after a successful check and one on a source problem. The JSON result carries diagnostics; ordinary text output also names the file, line and column. A project that needs a DAWN update or a format migration stops with exit three and a corrective command.

Use the vendored SDK’s existing builders, or update DAWN and review the SDK changes. dawn migrate shows a proposed migration; dawn migrate --apply writes it and retains a backup.

A project made by dawn init records a trace in trace/: each check, render and source change, including the edits the agent makes directly to song.ts and the track files, with the revision before and after. Ask the agent to add what only it knows: the request it was given, the decisions it made and a handoff before it stops.

Terminal window
export DAWN_TRACE_AGENT="Claude Code" # or "Codex"; names the agent on captured commands
dawn trace note --kind prompt --text "Add a quieter piano answer in the chorus"
dawn trace note --kind decision --text "Piano an octave below the lead; bass and drums untouched"
dawn trace note --kind heard --text "The answer is audible at bar 17 without masking the vocal"
dawn trace note --kind handoff --text "Next: check the piano level against the pad, then render"

dawn trace note assigns the event ID and records against the project’s current revision; it evaluates the project to learn that revision unless --base is given. Record concise reasons and observable results, not a whole conversation or internal reasoning. Credential-shaped text is replaced by [redacted], but keep credentials out of notes in the first place.

trace/ is committed with the song, so a git push publishes every prompt, note and comment recorded there. Run dawn trace enable . --no-text to keep metadata only, or dawn trace disable . to stop recording. The trace reference lists what each command records.

Interface Use
TypeScript SDK Author notes, tracks, instruments, effects, automation and song form
dawn check --json Read structured project diagnostics
dawn lint --json Check musical structure and register
dawn measure --json, dawn mixqa --json Read audio measurements and mix checks
dawn render Export audio, MIDI, stems or score JSON
dawn workflow Inspect and resume durable song jobs
dawn changes --json, dawn migrate --json Inspect compatibility changes
dawn trace note, dawn trace read --json Record and read requests, decisions, handoffs and project history

Preserve a quality report and its rendered input together. Optional learned judges, local models, vocals and media helpers have their own setup and compute requirements; use the workflow guide before invoking them.

The CLI reference, SDK guide, complete SDK API reference and score schema describe these shared interfaces. The workflow uses local files and commands and works independently of an agent vendor.

Documentation drafted with AI and checked against the product source.