protozoan

AI-powered dev overlay — wrap any dev server with a chat panel and element annotation tools.

Install

npm install -g protozoan

Or run without installing:

npx protozoan dev -- vite

Usage

protozoan dev -- <your-dev-server-command>

# Examples
protozoan dev -- vite
protozoan dev -- next dev
protozoan dev -- webpack serve
protozoan dev -- npm run dev

Protozoan starts on port 3000 by default and proxies your dev server transparently. Open http://localhost:3000 — your app loads normally with a Protozoan toolbar injected in the corner.

Setup

Set your OpenRouter API key (free tier available):

export OPENROUTER_API_KEY=sk-or-...

Or add it to a .env file in your project root.

Environment variables

| Variable | Default | Description | |---|---|---| | OPENROUTER_API_KEY | — | Required. Your OpenRouter API key. | | PROTOZOAN_PORT | 3000 | Port for the Protozoan proxy. | | PROTOZOAN_MODEL | openai/gpt-oss-120b:free | Any OpenRouter model. |

What it does

• AI chat — describe a change in plain language, Protozoan applies a diff to your source files and your existing HMR picks it up instantly
• Annotations — click any element on the page to leave a persistent note pinned to that element; annotations survive reloads and are stored in .protozoan/annotations.json

Full docs

See the repository README for complete documentation.