npm package: @honch/honcho
Description: CLI tool that generates AI-ready Honch SDK installation instructions for any JavaScript framework
Author: Honch
Latest version: 1.0.1

# honcho

`npx @honch/honcho` generates a single instruction file that tells your AI coding assistant exactly how to add Honch analytics to your project. No docs to read, no boilerplate to copy — just answer a few questions and hand the output to Claude, ChatGPT, Cursor, or whatever you use.

## Quick start

```bash
npx @honch/honcho
```

You'll be asked for your API token, which framework you're on, and what kind of events you want to track. Honcho writes everything into `HONCH_INSTALLATION_INSTRUCTIONS.txt`. Drop that file into your AI agent's context:

```
Set up Honch analytics by following HONCH_INSTALLATION_INSTRUCTIONS.txt.
Follow the global rules in the file. Delete the file when you're done.
```

That's it. The agent handles the rest — installing the package, initializing the SDK, wiring up identify calls, and placing event captures throughout your code.

## Supported frameworks

| Flag           | What it covers                              |
| -------------- | ------------------------------------------- |
| `javascript`   | Script tag, CDN, vanilla JS                 |
| `react`        | React, Next.js (App Router + Pages Router)  |
| `vue`          | Vue 3, Nuxt 3                               |
| `angular`      | Angular with injectable service pattern      |
| `svelte`       | Svelte, SvelteKit                           |
| `npm`          | Any bundler — generic ESM / CJS import      |

## Event templates

Pick the one closest to your product:

- **default** — Sign up, sign in, page views, search, errors, conversions
- **saas** — Feature usage, onboarding steps, invites, plan changes, integrations, usage limits
- **ai** — Prompt sent, response received, token/cost tracking, feedback, dismissals
- **ecommerce** — Product viewed, add to cart, checkout, purchase, coupons

Templates are starting points. The instruction file tells the AI to adapt event names and properties to your actual codebase.

## SDK features you can toggle

| Feature              | What it does                                       | Default |
| -------------------- | -------------------------------------------------- | ------- |
| Autocapture          | Tracks clicks, form submissions, and pageviews     | On      |
| Session Recording    | Records sessions via rrweb for replay in dashboard  | On      |
| Web Vitals           | Captures LCP, FID, CLS, and other Core Web Vitals  | On      |

## Non-interactive mode

Pass everything as flags to skip the prompts:

```bash
npx @honch/honcho \
  --token YOUR_TOKEN \
  --platform react \
  --events saas \
  --autocapture \
  --session-recording \
  --web-vitals
```

Other flags:

- `--confirm-each` — forces the AI to show a diff and wait for approval before each code change

## How it works

Honcho doesn't touch your code. It builds a structured prompt — install steps, identify patterns, capture examples, and an event schema — written specifically for LLMs to follow. The output is plain text, so you can read it, edit it, or version-control it before handing it off.

The generated instructions tell the AI to:

1. Install `@honch/sdk` and initialize it once at the app root
2. Wire `honch.identify()` into your auth flow
3. Place `honch.capture()` calls at the right spots based on the event template
4. Use environment variables for the token in production
5. Never touch unrelated files or do broad refactors

## Prerequisites

- A [Honch](https://honch.io) account and your project API token (found in project settings)
- Node.js (for npx)
- An AI coding assistant with access to your project files

## After setup

Deploy to a test environment, use the app for a minute, then check your [Honch dashboard](https://app.honch.io). Events should appear within seconds. If nothing shows up, make sure `debug: true` is set and check the browser console for Honch log output.

## License

Apache 2.0 — see [LICENSE.md](LICENSE.md).