Install with the wizard

What the wizard is

The CLI wizard is a command you run in a terminal inside your application folder. It:

1. Opens a browser so you can Approve access to HumanBehavior (device login).
2. Detects your JavaScript framework(s).
3. Starts an AI agent that installs humanbehavior-js and wires init code in the correct file(s).
4. Writes environment keys.
5. Runs project checks (lint/typecheck/build scoped to edits).
6. Has the host (not only the AI) judge whether the install is trustworthy.
7. Leaves humanbehavior-install-report.md in your project.

Package to run:

npx @humanbehavior/wizard@latest

Runtime package it installs: humanbehavior-js.

How this differs from in-app “Install with AI”

You only need one successful install path.

Prerequisites

• Node.js installed (node -v works).
• A JS browser app (Next, React, Vue, Svelte, Remix, Nuxt, Astro, Angular, Gatsby, or bundled HTML).
• A HumanBehavior account (so Approve works).
• Network access to Anthropic via HumanBehavior’s gateway (normal path) or a documented local override for benchmarks only.

Step-by-step

1. cd to your app root (or the frontend package in a monorepo).
2. Run npx @humanbehavior/wizard@latest.
3. When the browser opens, sign in if needed and click Approve.
4. Return to the terminal. Watch status lines (detect → edit → revise → done).
5. Open humanbehavior-install-report.md and read what changed.
6. Start your app and complete Verify.

What “supported” means

The wizard will install for detected browser frameworks and bundled HTML (Vite/webpack/etc.).

The wizard will refuse early for:

• Backend-only Python (and similar non-JS)
• Unbundled static CDN-only HTML with no JS app structure

That refusal is intentional. A false “You're good to go” on a Flask API would be worse.

Outcomes you may see

Failed installs set a non-zero process exit code (useful in scripts).

What the host checks after the agent (plain English)

The host can downgrade a cheerful agent “success” if it can prove problems such as:

• Unsupported project type
• Missing install target
• Bad HumanBehaviorTracker.init signature (e.g. URL as second positional arg)
• Empty API key / unsubstituted env placeholders
• Env/dependency written outside the chosen app
• .env read via filesystem tools (policy violation)

Soft issues after structural wiring → needs-attention, not silent success.

Performance / behavior notes (so you are not surprised)

• Typical successful installs take about 1–3 minutes, sometimes longer on Next.js or large repos. This is an agentic installer, not a 10-second script.
• Default turn budget is 75 (HB_WIZARD_MAX_TURNS can raise it for local debugging).
• The host preinstalls the install skill and can skip package install when humanbehavior-js is already up to date.
• Direct Read/Grep/Bash on .env* files is denied; env must use wizard env tools.

Local agent key (benchmarks / debugging only)

For local matrix testing you can set HB_WIZARD_ANTHROPIC_API_KEY so the install agent uses your Anthropic key. Optional host overrides the CLI already reads:

• HB_DASHBOARD_URL
• HB_INGESTION_URL
• HB_WIZARD_MODEL
• HB_WIZARD_MAX_TURNS
• HB_WIZARD_DEBUG=1
• HB_TARGET_CWD / INIT_CWD

Without HB_WIZARD_ANTHROPIC_API_KEY, the wizard uses its normal hosted agent path. Do not rely on these overrides in CI that serves real users.

Common failures and fixes

Related

• Manual install
• Wizard
• Common install failures
• Verify