Work with a coding agent
For agents
Give your agent this page’s Markdown link, or choose a collection.
- Documentation indexFind a guide and its Markdown link.
- Full documentationRead all curated guides in one text file.
- Machine manifestFind page metadata, Markdown URLs and checksums.
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.
Set up the project
Section titled “Set up the project”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.
Give the agent a complete task
Section titled “Give the agent a complete task”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.
Use the edit loop
Section titled “Use the edit loop”- Edit
song.tsortracks/<slug>/track.ts. - Run
dawn check --jsonand fix the reported problems. - Run
dawn render review.wav --measureand inspect the result. - Run
dawn render review.midwhen 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.
Record requests and decisions
Section titled “Record requests and decisions”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.
export DAWN_TRACE_AGENT="Claude Code" # or "Codex"; names the agent on captured commandsdawn 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.
Pick the interface for the task
Section titled “Pick the interface for the task”| 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.