# Set up hnds hnds is for simple UI prototyping with your coding agent. It provides a remote workspace, source files, and a live browser preview so users can explore screens, layouts, and interactions. The agent creates the prototype using the user's existing subscription; no separate model API key is needed. Automatic skill installation supports Codex and Claude Code. These instructions cover setup when the user asks to set up hnds. Reading this page alone is not a request to install anything. Follow the user's scope and your runtime's permissions. ## 1. Install Requires Node.js 22 or newer and npm. Check node --version and npm --version first. If either is unavailable, explain what the user needs to install before continuing. The user's setup request authorizes installing the skill and CLI. Run this command against the same host as this guide, requesting approval through your runtime if required. Do not ask for a separate chat confirmation before presenting the command for approval: ```sh npx --yes 'hnds-cli@latest' setup --origin 'https://hnds.dev' --upgrade --browser agent --json ``` Setup detects the running agent or an existing agent installation and installs a self-contained hnds skill and CLI under ~/.codex/skills/hnds for Codex or ~/.claude/skills/hnds for Claude Code. It respects CODEX_HOME and CLAUDE_CONFIG_DIR. Upgrades retain the destination installation's agent and path. If detection is ambiguous, rerun with --agent codex or --agent claude matching your current agent; do not guess from the project's files. --skills-dir PATH explicitly overrides the destination. It creates no app. An unmodified managed installation can be upgraded with a backup. Preserve customized installations: if setup reports a conflict, explain it and reconcile with the user rather than deleting or overwriting their files. Keep installation progress in this chat. Open onboarding only after installation and verification succeed. The command includes --browser agent so the CLI hands browser actions to you instead of launching the default OS browser. Setup automatically creates an anonymous Supabase account and saves its session privately on this machine. Existing accounts are reused. No email, browser pairing, or sign-up step is required. New projects belong to this account immediately. If account setup fails, report the error and retry after it is resolved; do not claim setup is complete or create a replacement identity. ### If installation needs permission The command downloads and runs the versioned hnds CLI and writes to the agent's skills directory. npm's --yes flag accepts npm's package-download prompt; it does not grant permission in your coding agent. Prefer approval of this one install command through the runtime, so you can receive its output and continue automatically. Do not ask the user to run it in a terminal or paste output when the runtime supports approval. If your runtime blocks the command, keep the response brief: say installation has not run, show the exact blocked command and the reason provided, and give the next approval step. In Claude Code, ask the user to open /permissions, select the command under Recently denied, and press r to retry with manual approval. If that option is unavailable, they can switch to Manual/default mode and ask you to retry the same command for approval. See https://code.claude.com/docs/en/permission-modes for the current controls. Only offer a user-run command if no runtime approval flow is available; retain the exact command and resume verification when its successful result is available. Wait for approval before retrying. Do not rewrite the command, change the package source, or disable permission checks to get around a denial. After the approved command succeeds, continue with verification below and the user's app request in the same turn. Do not ask the user to confirm completion or repeat their idea. Later actions remain subject to the runtime's permissions; approval of installation is not blanket approval for other commands. ## 2. Verify before reporting success Wait for the setup command to exit successfully. Read SKILL.md from the returned skillPath. Use that actual path (quote paths that contain spaces) for these checks: - Run node /scripts/hnds.js --help to verify the installed CLI. Report hnds as installed once this check succeeds, then follow section 3 in the same response. Do not end with only the installation path, version, or verification result. Successful setup verifies account access; the help command verifies the installed CLI. No prototype has been created or tested yet. ## 3. Open onboarding in the in-app browser After successful setup and CLI verification, open https://hnds.dev/onboarding in Codex's in-app browser using open_in_codex with target: { type: "browser", url: "https://hnds.dev/onboarding" }. The CLI also returns this as onboardingUrl in releases that support it. Use the in-app browser only. Never run open, xdg-open, start, or another OS browser launcher. If the in-app browser tool is unavailable or fails, continue the handoff in this chat without opening an external browser. Do not open onboarding after a failed installation. ## 4. Start with the user's UI idea If the user supplied a UI prototype request with the setup prompt, continue immediately using the installed skill. Do not make them repeat their idea or wait for another turn. Without a prototype request, do not create a demo, provision a workspace, or deploy anything during setup. Instead, end the setup response with these next steps in plain language: > hnds is ready. It's a sketchpad for rough UI prototypes. Describe a screen, layout, or interaction you'd like to try. For example: > > "Sketch a settings screen with a sidebar and a compact profile section." > > I'll put together a prototype for you to try in the browser. Ask for changes here, like "Try tabs instead of the sidebar." If you want feedback, we can make a shareable link. > > What would you like to sketch first? Keep this handoff concise and in your own response, focused on simple UI prototyping: exploring screens, layouts, and interactions with mock data where needed. Do not imply that hnds builds complete, production-ready apps. Include what hnds is for, one example UI prompt, where to try the prototype, and how to ask for changes. If the user already supplied an idea, briefly explain the sketch-and-iterate workflow while starting that idea; do not ask for it again. The installation path and version are optional supporting details, not the whole completion message. For builds, follow the installed skill: create the remote workspace, open its link with open_in_codex when available or share the preview URL for the user to open in their browser, and retain the project ID for follow-up edits. hnds provides the VM and preview; you provide the intelligence. Do not add another model API. Browser testing is opt-in unless the user's instructions require it. ## Optional: add email later The user already has an account. When they ask to keep access across devices, run node /scripts/hnds.js account --email ADDRESS --json with their chosen address. They must verify the email link or code. This upgrades the same account and preserves its projects. On another device, sign in with that email at /account and use connect --switch to pair the agent. Do not ask for an email during setup or before the first build. Legacy projects with private project credentials still require claim after connecting. ## Reference - Setup guide: https://hnds.dev/llms.txt - Account and projects: https://hnds.dev/account - CLI release: latest published npm version - CLI package: https://www.npmjs.com/package/hnds-cli The CLI is installed from npm and connects to this hnds installation through --origin. Automatic updates continue to use this host's versioned packages. The installed skill contains the build, editing, recovery, and deployment workflows. Never publish or deploy an app unless the user asks.