build_async
Destructive
Start a long-running autonomous build in the background, returning immediately with a run_id. Poll job_status to watch progress or stop_job to cancel.
Instructions
Start an autonomous build in the BACKGROUND and return immediately.
Use when: the build may run for minutes and you want to keep working — this
returns a ``run_id`` right away instead of blocking (as the synchronous
``build`` does) until the run finishes. Poll ``job_status`` with the
``run_id`` to watch progress, ``stop_job`` to cancel, ``list_jobs`` to see
everything running. Do NOT use for a quick preview — use ``build`` with
``dry_run=True``. Related: ``build`` (synchronous), ``report`` (final outcome).
DESTRUCTIVE side effects (once running): edits files, makes git commits, and
calls an external LLM provider. Refuses to start a second job for a project
that already has one running (one writer per project).
Returns ``{run_id, status}`` on success, or ``{error}`` when a job is already
running for this project.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | What to build, or a mode word ('debug', 'complete', 'review'). Example: 'add rate limiting to the public API'. | |
| path | Yes | Absolute path to the project directory to build. Its git working tree must be clean. Example: '/Users/me/code/my-api'. | |
| budget | No | Maximum US dollars to spend; must be > 0. | |
| parallel | No | Run independent tasks concurrently in worktrees. | |
| max_tasks | No | Cap how many tasks are planned/executed; >= 1. | |
| reference_dir | No | Optional reference implementation to port from (analyzed read-only). See the synchronous ``build`` tool. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |