# @dxyz/oneshot

**Arm your machine once. Then one-shot apps from a single prompt.**

A setup CLI and a build protocol. It installs the tools, walks every login and verifies each one, and teaches Claude Code two commands: `/oneshot` builds a new app until it is live on the internet, `/reshot` edits a live app without changing its url.

```bash
npx @dxyz/oneshot
```

## Start here

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

```bash
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:

```bash
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.

```bash
/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:

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

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

```bash
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.

Source: https://doranalytics.xyz/npx/oneshot