site-facelift 0.1.2

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+
• 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 site-facelift

The PyPI distribution is site-facelift, but the installed CLI command and Python module are both facelift (the unprefixed facelift name on PyPI was already taken).

If you'd rather install from source, clone this repo and run uv sync (or any other Python build frontend that understands pyproject.toml).

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