pAInt

pAInt is a visual editor for localhost web projects. It helps you inspect elements, edit styles, manage CSS variables, and export changelogs for Claude Code.

Table of Contents

• Project Status
• Global CLI
• What You Can Do
• Prerequisites
• Quick Start
• Connection Modes
• Core Workflow
• Interface Layout
• Commands
• Architecture Summary
• Security Notes
• Documentation
• Contributing
• Release Automation
• License

Project Status

• Stage: Active development
• Stability: Suitable for local development workflows
• Scope: Visual editing and changelog-driven code updates for localhost apps

Global CLI

Install globally with your package manager of choice:

npm install -g @antigenic-oss/paint
pnpm add -g @antigenic-oss/paint
bun add -g @antigenic-oss/paint

Requires Node.js >=20.9.0.

If paint is not found after install, add your global bin directory to PATH once:

# Bun
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# npm (uses npm global prefix)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# pnpm
pnpm setup

After install, run:

paint help
paint start

Then use:

paint start             # Builds on first run, then starts web server
paint status            # Show web status
paint stop              # Stop web server
paint restart --rebuild # Force a rebuild before start
paint logs              # Print web logs
paint terminal start    # Start terminal websocket server
paint terminal restart
paint terminal status
paint terminal stop
paint bridge start      # Start bridge server
paint bridge restart
paint bridge status
paint bridge stop

Default URL: http://127.0.0.1:4000 Terminal WS (when started): ws://localhost:4001/ws

What You Can Do

• Inspect and select any element in a live preview
• Edit typography, spacing, layout, colors, borders, shadows, and gradients
• Manage and reuse CSS custom properties
• Work across breakpoints (Mobile 375px, Tablet 768px, Desktop 1280px)
• Navigate and select through a DOM layers tree
• Insert new HTML elements from the Add Element panel
• Track every change and export a structured changelog
• Send changelogs to Claude Code for source-file application

Prerequisites

• Local repository development: Bun >=1.3
• Global CLI runtime: Node.js >=20.9.0
• A localhost app running in development mode (Next.js, Vite, Astro, CRA, etc.)

Quick Start

bun install
bun dev

Open http://localhost:4000, then:

1. Start your target app (for example http://localhost:3000)
2. Select the target localhost port in pAInt
3. Click Connect
4. Start inspecting and editing

Connection Modes

Automatic proxy mode (default)

Click Connect and pAInt loads your page through its reverse proxy, injecting the inspector automatically.

Manual script mode

If auto-injection is not detected, add this script tag to your app layout and reload:

<script src="https://dev-editor-flow.vercel.app/dev-editor-inspector.js"></script>

Vercel + local bridge mode

If the UI is hosted on Vercel, run the local bridge server:

paint bridge start

Bridge default: http://localhost:4002

Core Workflow

1. Connect to your localhost app
2. Select elements from preview or Layers
3. Edit styles in Design/Variables panels
4. Review edits in Changes
5. Copy changelog or send it to Claude Code

Interface Layout

• Left panel: Layers, Pages, Components, Add Element, Terminal
• Center panel: Live iframe preview
• Right panel: Design, Variables, Changes, Claude, Console

Commands

bun install                # Install dependencies for local repo development
bun dev                    # Start UI (localhost:4000)
bun run bridge             # Start bridge server (localhost:4002)
bun run dev:terminal       # Start terminal server
bun run dev:all            # Start terminal + bridge + Next.js dev server
bun run build              # Production build
bun run start              # Production server (port 4000)
bun run lint               # Biome check

Architecture Summary

• Next.js App Router frontend (develop locally with Bun, run globally via Node.js CLI)
• Proxy API route at /api/proxy/* for target-page loading and injection
• Inspector script communicates with editor via window.postMessage
• State managed with Zustand slices
• Changes persisted in localStorage per target URL

Security Notes

• Localhost targets only
• Proxy rejects non-local addresses
• Target-page scripts are stripped in proxy mode to reduce runtime interference
• CLI execution is spawned without shell-string interpolation

Documentation

• In-app docs: /docs
• Contributor guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security reporting: SECURITY.md
• Support details: SUPPORT.md

Contributing

See CONTRIBUTING.md for setup, workflow, and pull request expectations.

Release Automation

• Versioning and release PRs are managed with Changesets.
• CI workflow: .github/workflows/ci.yml
• Release workflow: .github/workflows/release.yml
• Publishing uses npm Trusted Publishing (OIDC) from the release GitHub Environment.
• To queue a release, add a changeset:

bun run changeset

License

Apache License 2.0. See LICENSE.