site-facelift 0.1.0

Give old, outdated small-business websites a modern, AI-orchestrated facelift.

Facelift

Give any old, outdated website a modern facelift — fully automated, AI-driven, end-to-end.

What it does

Facelift crawls a target website and downloads every page and asset, then sends each image to Gemini Flash 3.1 for a structured design-oriented description. Claude analyzes the downloaded content and image sidecars to produce a brand analysis, then generates a detailed design brief, and finally implements the redesigned site as a Next.js + Tailwind project. A mechanical validation pass checks for typos, broken links, and image misuse; a final Claude step applies obvious fixes and logs judgment calls for human review. See plan.md for full pipeline detail.

⚠️ Footgun: --dangerously-skip-permissions

Facelift always invokes Claude Code with --dangerously-skip-permissions. That gives Claude unrestricted tool access, including arbitrary shell commands, on every step. This is required for the pipeline to run unattended, and it is not user-configurable. If you are not comfortable with that, do not run facelift.

Prerequisites

• Python 3.11+
• uv (only if installing from source)
• Claude Code installed and authenticated (claude --version should print)
• The frontend-design skill installed in your Claude Code setup
• Node.js 20+ and npm (used by step 5 to scaffold the Next.js project)
• A Gemini API key in the GEMINI_API_KEY environment variable

Install

pip install facelift

Usage

mkdir my-clients-facelift && cd my-clients-facelift
export GEMINI_API_KEY="..."
facelift www.examplebadwebsite.com

Facelift writes everything to the current working directory: download/ holds the raw scraped site (HTML, CSS, images, and all assets), plan/ holds the markdown planning artifacts (brand analysis, design brief, validation report, deferred decisions), and site/ is the finished Next.js + Tailwind project ready for npm run dev. facelift.log captures the full run log. A STEPN_COMPLETED sentinel file is written for each finished step. Re-running in the same directory picks up where it left off — any step whose sentinel is present is skipped automatically.

Output layout

./                           # cwd; one facelift run per directory
  facelift.log               # full run log
  STEP1_COMPLETED            # progress sentinels (see Resumability)
  STEP2_COMPLETED
  ...                        # one per completed step
  download/                  # raw scraped site (HTML, CSS, images, videos, all assets) + per-image sidecars
  plan/                      # planning markdown artifacts
    brand-analysis.md
    design-brief.md
    validation.md
    deferred-decisions.md
  site/                      # Next.js + Tailwind project — the modernized site (step 5 output)
    DEVIATIONS.md            # only present if step 5 deviated from the design brief
    node_modules/            # left in place so `npm run dev` works without reinstalling

Resumability

Step-level progress is tracked with STEPN_COMPLETED sentinel files at the run root. When a step finishes cleanly its sentinel is written; on the next run, any step whose sentinel exists is skipped. To force a step to re-run, delete its sentinel (and those of all downstream steps you also want redone). Steps 1 and 2 have additional per-item resumability: the crawler skips URLs whose output file already exists, and the image describer skips images whose sidecar already exists, so a mid-step crash picks up at the next unfinished item rather than restarting from scratch.

Troubleshooting

• claude: command not found — install Claude Code from https://docs.claude.com/claude-code and make sure it's on your PATH.
• Claude not authenticated — run claude /login and complete the authentication flow before re-running facelift.
• Missing frontend-design skill — the skill is not detected at runtime; if it isn't installed, step 4 will still run but produce less distinctive design output. Install it in your Claude Code setup.
• GEMINI_API_KEY not set — facelift fails fast on startup with a clear error; export the variable and re-run.
• Gemini quota / rate-limit (HTTP 429) — fatal in v1; re-run after your quota resets. Sentinel-based resumability means step 2 picks up at the first un-described image.
• npm: command not found — install Node.js 20+ (which includes npm) from https://nodejs.org/.

License

MIT