tentwenty-design-pilot

v1.2.0

Published

17 days ago

Dev-only AI design companion for React apps, powered by a headless Claude Code session — click a component, prompt a design change, watch real code edits land live via HMR, undo per prompt via git checkpoints, push when happy. Built for design teams.

0High
0Medium
0Low

npm_tentwenty

react nextjs design ai claude claude-code agent devtools tailwind overlay design-assistant

tentwenty-design-pilot

A dev-only AI design companion for React apps, powered by a headless Claude Code session. Click any component in your running app (or just describe what you want) — Claude explores your codebase, makes real design edits across the right files, and your dev server hot-reloads them live. Every prompt is git-checkpointed: one click undoes it. When it's right, one click commits and pushes.

Built so a design team can iterate on a product's UI through prompts — deployable on an internal server with a shared collaborative session.

Highlights

Real edits, not previews — a genuine Claude Code agent works in your repo (multi-file, design-system-aware); HMR shows the actual result
Click-to-target — a DevTools-style picker resolves any element to its React component source file (React 18/19, webpack & Turbopack)
Reference designs — attach/paste images, or paste a URL and the pilot screenshots the site as a visual target
Safe by construction — the agent may only edit .tsx/.jsx/.css (configurable); APIs, configs, package.json, env files are hard-blocked; no shell access; nothing pushes without the button
Undo anything — git snapshot per prompt (no branch switching); Undo last / Discard all / Confirm & Push
Safe push — Confirm builds the commit off to the side and pushes it straight to the remote design branch (auto-created): your local branch and worktree are never touched, so the checkout can't diverge
Portable git auth — one env token (Bitbucket access token / GitHub PAT) is all a server needs: injected at push time, never written to disk, redacted from errors; SSH remotes auto-convert. Works with Bitbucket, GitHub, GitLab — any HTTPS remote
Team-ready — shared chat, one-change-at-a-time lock with names, designer credit on commits (author = designer), session survives reloads and restarts

Quick start

npm install -D tentwenty-design-pilot

# .env.local — the pilot server auto-loads this; nothing reaches the browser
ANTHROPIC_API_KEY=sk-ant-...          # required on servers; dev machines can fall back to a local Claude Code login
ENABLE_DESIGN_PILOT=true              # gates the auto-start; false/absent = fully off

# Optional env overrides (these beat design-pilot.config.ts):
DESIGN_PILOT_MODEL=claude-opus-4-8    # Claude model for the agent
DESIGN_PILOT_EFFORT=low               # low | medium | high | xhigh | max
DESIGN_PILOT_BRANCH=design-updates    # remote branch Confirm pushes to (auto-created)
DESIGN_PILOT_GIT_TOKEN=               # HTTPS push auth: Bitbucket access token (Repositories: Write) or GitHub PAT — required on servers unless SSH auth exists
DESIGN_PILOT_GIT_USER=x-token-auth    # default; set your username when using an app password
DESIGN_PILOT_REPO=                    # explicit push URL — only for deployments that aren't a git clone

// next.config.ts
import { withDesignPilot } from 'tentwenty-design-pilot/next';
export default withDesignPilot(nextConfig);

// app/layout.tsx — inside <body>, after your app
import { DesignPilot } from 'tentwenty-design-pilot/react';
<DesignPilot />

Run next dev — the pilot server starts and stops with it. Open your app, hit the ◆ button, and prompt away. (Non-Next setups: run npx design-pilot alongside your dev server.)

<DesignPilot /> renders nothing in production builds, so it can live in your layout permanently.

The loop

⌖ pick a component (optional) → "make the stat cards glassmorphic with a soft glow"
   → Claude explores, edits the right files → change is LIVE via HMR
   → happy? keep going (full session context carries over)
   → not?  ↩ Undo last · Discard all
   → done? Confirm & Push — one commit, prompts as the message, designer credited

Configuration (optional)

Everything works with zero config. Settings come from env vars (above) or design-pilot.config.ts at the project root — env always wins, which makes per-server overrides trivial:

export default {
  agent: { model: 'claude-opus-4-8', effort: 'low', maxTurns: 25 },
  files: { allow: ['**/*.tsx', '**/*.jsx', '**/*.css'], deny: [] },
  git:   { remote: 'origin', branch: 'design-updates' },
  server:{ port: 3141 },
};

How pushing resolves: the repo comes from the clone's own origin (no setting needed); the branch is auto-created on first push; auth is the env token on servers or your existing git auth locally. Deployments without a .git folder still work — the pilot initializes a local repo for checkpoints and pushes to DESIGN_PILOT_REPO.

Documentation

docs/USAGE.md — full setup, workflow, safety model, troubleshooting, costs
docs/DEPLOY.md — running it on an internal server for a design team

Requirements

Node 18+ and the git binary (the one system dependency — npm can't install it; the pilot checks at startup and tells you how to install if missing)
React 18+ in development mode
An Anthropic API key (or a local Claude Code login on dev machines)
Optional: playwright in the host project enables visual screenshots of reference URLs

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

tentwenty-design-pilot

Highlights

Quick start

The loop

Configuration (optional)

Documentation

Requirements

License