build
Scaffold an idea into a project and launch your AI coding agent.
build is the heart of the CLI. It fetches an idea's playbook, scaffolds a
project, and launches your agent on it. Grab an idea's id from
hackspot list (or its URL on the site, /app/ideas/<id>).
npx @hackspot/cli build 42 # scaffolds ./<idea-slug>/ and launches your agent
npx @hackspot/cli build 42 ./my-app # choose the directoryBy default it scaffolds into ./<idea-slug>/. Pass a second argument to choose
the directory. A non-empty directory is refused unless you pass --force.
Scaffolded files
It writes three files into the target directory:
| File | Purpose |
|---|---|
AGENTS.md | The playbook as the cross-tool context file agents auto-read. |
PROMPT.md | The bootstrap instruction (paste into any agent). |
hackspot.json | The structured idea (id, pitch, MVP, demo, event brief). |
Choosing an agent
After scaffolding, the CLI launches an agent in that directory, inheriting your
terminal. With no --agent, it auto-detects the first installed of claude →
codex → opencode.
--agent value | Runs |
|---|---|
claude | claude "<bootstrap prompt>" |
codex | codex "<bootstrap prompt>" |
opencode | opencode run "<bootstrap prompt>" |
"<command>" | Any command — see below. |
For a custom command, include {prompt} to substitute the bootstrap prompt;
otherwise it's appended as the final argument:
npx @hackspot/cli build 42 --agent "my-agent --task {prompt}"
npx @hackspot/cli build 42 --agent "my-agent" # prompt appended as last argNo agent installed? build still scaffolds the files, then prints the command
to run. Your agent will read AGENTS.md; PROMPT.md holds the bootstrap prompt.
Flags
| Flag | Description |
|---|---|
--agent <name> | Agent to launch, or a custom command. |
--no-launch | Scaffold only; print the command. |
--force | Allow a non-empty target directory. |
--dev | Target http://localhost:3000. |
--base-url <url> | Target a custom base URL. |