Getting Started

Dev mode is the fastest way to feel what Paintless does: click an element, describe a change, watch a local agent apply it with HMR, then commit it from the browser.

#Quick start: npm create paintless

The interactive setup detects your framework, bundler and package manager, then installs the right packages, writes paintless.config.ts, and prints the two snippets to paste in:

npm create paintless@latest

Detected: react · vite · pnpm
✔ Which framework?              › React
✔ Which bundler?               › Vite
✔ How will you use Paintless?  › Dev — a local agent edits the code
✔ Which agent?                 › Claude Code
→ installs @paintless/react + @paintless/mapper-vite
→ writes paintless.config.ts
→ prints the vite.config and widget snippets

Press Enter to accept each detected default, or add --yes to skip the prompts entirely. Add --no-install to write the config and print the steps without installing. The rest of this page is the same setup done by hand.

#1. Add the source mapper

The mapper annotates elements with the file and line they render from, so the picker can point the agent at the exact source location.

For Vite + React:

// vite.config.ts
import { paintlessMapper } from '@paintless/mapper-vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [paintlessMapper(), react()],
})

Using webpack, Next.js, or Vue? See Source Mapping.

#2. Mount the widget

import { Paintless } from '@paintless/react'

export function App() {
  return (
    <>
      {/* your app */}
      <Paintless />
    </>
  )
}

Vue, Svelte, or a plain script tag work too — see Widget & Bindings.

#3. Start the dev host

npx paintless dev

The dev host is a local WebSocket server the widget auto-connects to. Without a config file it runs the Claude Code agent (@anthropic-ai/claude-agent-sdk) against your project — any authenticated Claude Code install or ANTHROPIC_API_KEY works. To use a different agent or add delivery destinations, see Configuration.

#4. Click, describe, commit

1. Open your app and click the floating Paintless button.
2. Hover shows each element's source location; click the one to change.
3. Describe the change — "make this button green, rounder".
4. The run panel streams the agent's work; HMR shows the result live.
5. Commit creates a clean git commit, Discard reverts the change.

#What just happened

picker → ChangeRequest (selector, source location, styles, comment)
       → paintless dev (WebSocket)
       → agent edits your working tree
       → git detects the changed files
       → approve → commit

The same request shape flows through production too — a self-hosted server queues it, a human approves it, and a runner turns it into a branch, a PR, or a ticket. That story starts at Self-Hosting.