ShuaiMXu/happyhands

Give every UI change a reason.

A local workbench to find UI problems, repair them with coding agents, and review the result.

Get started / How it works / Website / 简体中文

HappyHands brings UI diagnosis, agent-assisted repairs and before/after review into one local workbench. Inspect pages and interaction states, start a scoped repair, then decide whether to accept the result and submit a draft pull request.

Product demo

37-second product demo.

https://github.com/user-attachments/assets/19607c8f-3fb4-4db5-826e-ff664980dbce

Get started

You need Git, Node.js 22.15+, pnpm 11.19, and an installed Chrome or Edge for browser capture. This source distribution provides the local workbench and Harness. Configure and sign in to Codex CLI to use the workbench’s built-in model diagnosis and visual review; implementation CLI setup depends on the executor you choose. See Use your coding agent for the distinction.

git clone https://github.com/ShuaiMXu/happyhands.git
cd happyhands
pnpm install --frozen-lockfile
pnpm workbench

Keep this terminal running. pnpm workbench starts the local HappyHands workbench and opens http://127.0.0.1:4190/apps/designer/. This address works on your computer after startup; it is not the public website or Theme Studio.

Make sure the product you want to review has a working preview. If it needs a local server, start it in a separate terminal using that project's own instructions. Confirm the preview URL opens in your browser, then connect the project in the HappyHands workbench with its local repository directory, preview URL and a specific user task.

The following is an example of the information to provide, not a terminal command. Replace the directory and URL with your project's actual values; port 3000 is only an example and is separate from the workbench's port 4190.

Repository: /path/to/your-product
Preview: http://localhost:3000
User task: Sign up and create the first project
Existing design sources (optional): DESIGN.md, src/styles/tokens.css, src/components

Design sources are optional references to files or directories that already exist in the product repository. The paths above are examples, not required files; use your actual paths and omit any that do not exist.

Check the proposed pages, devices and interaction states before capture. For configuration and command-line use, follow the Harness guide. The public website provides guidance and design resources; repository review and code changes run locally.

How it works

1. Inspect the pages. Connect your repository and preview, check the capture scope, then view desktop and phone screenshots with their issues. Switch devices, versions and interaction states without leaving the review. Click a screenshot to enlarge it in place.
2. Start a repair. Select Fix automatically. The workbench checks the diagnosed issues against current source, prepares the scope and plan, and runs the coding agent in an isolated Git worktree. It then captures the result and runs applicable checks and independent visual review. Missing evidence and failed checks remain visible.
3. Review the result. Compare before and after, then accept or reject the change. Acceptance reasons are optional; rejection and counter-evidence requests require a reason. An accepted, verified repair can be submitted as a draft PR through a separate action. The workbench does not merge or deploy it.

One repair action delegates the intermediate scope and planning steps; it does not accept the result for you. New interfaces without a baseline still require explicit Foundation approval before implementation.

What supports a finding

A reported defect needs a reproducible observation, an explanation of what is wrong, and a reference to the relevant skill snapshot. The Harness checks the cited section, line and quotation. General design advice and aesthetic preferences do not enter the automatic repair list on their own.

Repairs follow the reviewed product's own design sources. The HappyHands UI profile applies to the workbench and to projects that have explicitly adopted it. Original screenshots, earlier failures and excluded suggestions remain in the record. See the finding admission policy.

The HappyClaw review record shows how new counter-evidence led to an independent re-review while retaining the original failure. It documents that case's review path, not a whole-product acceptance or production deployment.

Design resources

The website provides Design.md references, design systems, components and Theme Studio. Use them to choose a direction, preview a theme and prepare design files for your project. They are optional inputs to the review; browsing a reference does not approve it as your project's design system.

Use your coding agent

HappyHands supports working with any AI CLI as part of an open coding-agent workflow. An external agent can operate the Harness with the necessary local terminal, repository and browser access, and changes made outside the Harness can be captured and reviewed. Direct execution through harness execute requires a registered adapter; the current default is Codex. This does not mean every CLI has built-in integration or that every feature has been validated with every CLI.

Run pnpm harness agents to inspect registered executors. Select one with harness execute --agent ID; --command PATH only changes that adapter’s binary location, not its CLI protocol. Other CLIs need an adapter for direct execution. External changes have no Harness agent-execution record and must be identified separately during review. Agent-specific behavior and limits are described in the adapter documentation.

Current scope

HappyHands is a free Local Web Alpha. External model and CLI services may require their own accounts, subscriptions or usage fees. Coverage follows the capture plan and completed checks; unseen pages and untested interactions remain unreviewed. Professional calibration, real-user acceptance and other gaps are tracked in the backlog.

Run records stay under .harness/. Model-assisted steps send selected source context and images to the configured model service through the CLI. Worktrees and repository checks are workflow safeguards, not a security sandbox. Review shared exports for sensitive material. See data and execution details.

pnpm dev             # Local development on port 4173
pnpm design:check    # Design documentation and integration contracts
pnpm test           # Engineering tests
pnpm regression     # Versioned release cases
pnpm build          # Contract checks and production build
pnpm harness skills # Registered methods and their maturity

Project links

Website / Harness guide / Roadmap / Issues

Follow the core project:

Star history

Original HappyHands source is licensed under MIT. Bundled third-party code and dependencies retain their own licenses, including tldraw’s separate production-use requirements. See third-party notices.