Install

Requirements

• Node.js 20 or newer
• An Anthropic API key (recommended) or OpenAI API key, or the Claude Code CLI installed
• macOS or Linux. Windows via WSL2.

Install

The one-shot setup script handles deps, build, Playwright browsers, and puts nitpick on your PATH:

git clone https://github.com/vaibhav-kindflow/nitpick.git
cd nitpick
./scripts/install.sh

That’s it. If you’d rather run the steps manually:

git clone https://github.com/vaibhav-kindflow/nitpick.git
cd nitpick
npm install
npm run build
npx playwright install --with-deps chromium
npm link              # makes `nitpick` available globally

If Playwright browsers ever need reinstalling (after an update or cache clear), use the built-in shortcut:

nitpick prep                   # chromium only (default)
nitpick prep --all-browsers    # chromium + firefox + webkit

Configure

Create a project directory for the app you want to test (one per app — keeps configs and KB isolated):

mkdir ~/my-app-qa && cd ~/my-app-qa
nitpick init

The wizard will:

1. Ask for project name + base URL
2. Offer a model picker after you choose a provider (e.g. gpt-5.4-mini → gpt-5.4 for OpenAI, claude-haiku-4-5 → claude-opus-4-6 for Anthropic), with rough per-run cost estimates. Your selection goes into llm.model plus a cheap llm.fast_model for scope decisions + the smoker.
3. Collect role credentials. The Login URL path is optional — leave empty for SPAs that auto-redirect or show a login modal on the base URL.
4. Accept persistent instructions — a free-form directive the scope router obeys on every run (e.g. “only test /tasks/new”, “skip billing”).
5. Pick critical pages, terminal guards, and an optional multi-role flow.

Writes nitpick.yaml and .env in the current directory. The .env is auto-loaded by the CLI on every run.

Verify

nitpick providers

You should see:

Available LLM providers:
  anthropic    Anthropic (direct API)          ✓ ready
  openai       OpenAI (direct API)             ✗ OPENAI_API_KEY not set
  claude-code  Claude Code CLI (subprocess)    ✗ claude CLI not found

One green check is enough.

Crawl your app

Before running tests, Nitpick needs to discover your app’s pages and save auth state:

cd ~/my-app-qa
nitpick crawl

For React / Vue / Angular apps that use client-side routing:

nitpick crawl --strategy agent

Takes 1–5 minutes. Run it once up front, then again whenever your navigation changes significantly.

Connect your IDE

Step 1 — install the skills bundle (enables slash commands in all IDEs):

cd ~/.nitpick && ./scripts/install-skill.sh

Step 2 — register the MCP KB server (lets you query test results from any conversation):

cd ~/my-app-qa && nitpick mcp register

mcp register detects which IDEs are installed and writes the config for each one automatically. No path hunting, no JSON editing.

KB path: /Users/alice/my-app-qa/knowledge-base

  ✓  Claude Code    registered
  ✓  Cursor         registered
  –  Codex CLI      not detected

Restart your IDE for the changes to take effect.

The host starts the MCP server on demand — nothing to run manually.

To update the KB path later (e.g. after moving the project):

nitpick mcp register --force

Claude Code

Open Claude Code in your project directory. The skills are picked up automatically. Type any command to start:

/qa-smoke
/qa-scope I refactored the login flow
/qa-run

Cursor

Use the same slash commands in Cursor’s chat panel after running the two steps above.

Codex CLI

After install-skill.sh, Codex picks up the skills from ~/.claude/skills/ automatically. Use the same slash commands in your Codex session, or run headless via the CLI:

cd ~/my-app-qa
nitpick run --scope smoke
nitpick run --scope iterative --change "I refactored the billing form"
nitpick run --scope full --non-interactive    # CI mode, no prompts

Next

→ Quickstart or jump straight to your first run.