@dxyz/oneshot — how to use it

Start here

Run this once, from any terminal. It arms the machine — you do not install anything by hand first.

npx @dxyz/oneshot

It walks four things, in order, and asks before each install: checks your machine (node, git, homebrew), installs the CLIs it needs, walks you through every login and re-checks each one before moving on, then writes the /oneshot and /reshot protocols into Claude Code.

Re-running is always the answer. Interrupted, expired login, half-finished — run npx @dxyz/oneshot again. Everything already done shows a ✓ and is skipped.

What you need before you start

Two accounts and a Claude Code login are the whole hard requirement. Everything else is optional and only bites when an app actually needs it.

Thing	Needed?	Why
macOS	Required in practice	v1 is built for macOS. Other platforms mostly work but fall back to manual install links.
Node 18+	Required	Runs the CLI. `brew install node` if the check fails.
git	Required	Every build is snapshotted before the first line of code. `xcode-select --install`.
Claude Code, logged in	Required	The thing that actually builds. Installed for you; you sign in with the Claude plan you already pay for.
GitHub account	Required	Keeps a copy of your code. Free tier.
Vercel account	Required	Puts the app on the internet. Free tier.
Homebrew	Recommended (macOS)	How the GitHub and Supabase CLIs get installed. Without it you install those two by hand.
Supabase account	Recommended	Only needed when an app has saved data or user accounts. Skip it and those apps hit a wall — you can add it later.
Apple Developer membership	Optional ($99/yr)	Only for real Mac apps. With it they ship signed, notarized, and stapled. Without it they ship honestly labeled "right-click → Open".
Your phone number	Optional	When a build finishes, your Mac texts you the live url over Messages. Enter to skip, "off" to turn it off later.

Logins are never trusted, only verified: after each browser flow it re-runs the check (gh auth status, vercel whoami, supabase projects list) and refuses to call itself armed until the check passes.

Building an app

Once armed, one word:

oneshot

It green-checks the rig in a few seconds — GitHub, Vercel, Apple signing if you armed it, Claude Code — then opens Claude Code with permissions bypassed. Type /oneshot and describe what you want. A sentence or five paragraphs; it is just a prompt, no quotes, no wrapper.

/oneshot a tide clock for my beach town — shows the next high tide,
big type, works on a phone

Then walk away. It does not stop to ask questions and it does not stop for permission prompts.

What "done" means

Done is a live production url anyone can open on their phone. Localhost is not done. A preview build is not done. And it is proven, not claimed:

the live url answers with a 200
the link unfurls — every app ships an OG share card, and the live og:image answers with a 200 too
a headless browser opens the real site, clicks through the core flow, and saves a screenshot as evidence
if the app has accounts, it creates a test account on the live site, logs out, and logs back in — auth that only works locally is not done
anything fails → it fixes, redeploys, and verifies again

The last line of its output is your link.

Changing an app that is already live

A one-shot is never the last shot. From the app's folder, one word plus the edit:

cd ~/dev/sand-clock
reshot make the cta button gold

Or from anywhere, if you name the app inside the edit:

reshot sand clock — show the tide chart first

Yes, that one line is the whole flow. Arming put a real reshot command on your machine: it green-checks your logins, then opens Claude Code with permissions bypassed and hands everything after the word reshot straight in as /reshot <your edit> — already running. No opening Claude Code first, no retyping the request inside it.

Same folder, same repo, same Vercel project: the live url updates in place and a new one is never created. Verified the same way as a one-shot. Already inside a Claude Code session? /reshot <edit> there does the same thing, minus the rig check. /oneshot births apps, /reshot raises them.

Commands

Command	What it does
`npx @dxyz/oneshot`	Arm the machine. First run, or any time something broke.
`oneshot`	Rig check, then open Claude Code armed. Type `/oneshot` to build.
`oneshot init`	Re-run the full arming flow — re-check tools, logins, phone, protocols.
`reshot`	Rig check, then open Claude Code ready for `/reshot`.
`reshot <edit>`	Same, with `/reshot <edit>` already running.
`/oneshot <idea>`	Inside Claude Code: build a new app until it is live.
`/reshot <edit>`	Inside Claude Code: edit a live app, same url.

The stack it picks

Next.js + Tailwind + shadcn/ui, deployed on Vercel, Supabase when the idea needs data or accounts. Boring, free-tier, best-documented — which is exactly what one-shots reliably. It is chosen for you on purpose; the fewer decisions in the prompt, the further the agent gets before it needs you.

Real Mac apps

Some ideas are not websites — menu bar tools, screen utilities. Those build on the native track: Swift, a real .app bundle, and a small download page on Vercel so the last line is still a live link. If you arm Apple signing during setup, every Mac app ships signed, notarized, and stapled, proven with Gatekeeper's own verdict (spctl). Your certificate and notarization password live in the macOS Keychain, never in a config file.

Where things live

Path	What
`~/.claude/commands/oneshot.md`	The `/oneshot` protocol, written for your machine.
`~/.claude/commands/reshot.md`	The `/reshot` protocol.
`~/dev/<app-name>/`	Every build. One folder per app, git-snapshotted before the first edit.

The blast radius is one folder. Your machine, your accounts, your code — free tiers of GitHub, Vercel and Supabase, plus the Claude plan you already pay for. Nothing to eject from later.

When it goes sideways

Symptom	Fix
"installed but not on PATH"	Close the terminal, open a new one, re-run `npx @dxyz/oneshot`.
npm install fails with EACCES	Your Node install needs an owner fix. Easiest path: `brew install node`, new terminal, re-run.
"login didn't stick"	Finish the steps in the browser tab, then re-run — it picks up where it left off.
"GitHub/Vercel login expired"	`npx @dxyz/oneshot`. Takes seconds when everything else is already armed.
"This machine isn't armed yet"	You ran `reshot` before arming. `npx @dxyz/oneshot` first.
Claude Code won't start	`npm install -g @anthropic-ai/claude-code`
Build stopped and wrote `BLOCKED.md`	It hit something a fix cannot produce — an account limit, an outage, a missing credential. The file says what it needs, in plain words.

Why this exists

The models can already one-shot. What kills one-shots is the machine: a Vercel login that expired, a CLI that was never installed, a build that stops to ask permission at minute two of forty. This arms the environment once — verified, not vibes — so the agent walks into a room where every door is already unlocked.