Quickstart

This quickstart gets Layrr running in front of a local web app, then walks through the first browser-based edit.

Prerequisites

• Node.js and npm.
• A local web app with a dev server, such as Vite, Next.js, Astro, SvelteKit, or another HTTP server.
• At least one supported coding agent: Claude Code, Codex CLI, or Gemini via Pi.

1. Start from the app you want to edit

Run your normal dev server first:

npm run dev

Keep this terminal running. Layrr will proxy requests to the dev server, so your app should be reachable before you start Layrr.

2. Run Layrr from npm

From the same project directory, start Layrr with the port your app is using:

npx layrr@latest --port 3000

If you want a reusable global command instead:

npm install -g layrr
layrr --port 3000

The npm package provides the layrr CLI.

By default, Layrr:

• serves the browser proxy at http://localhost:4567
• uses the current directory as the project directory
• prompts you to choose an agent if one is not configured
• supports Claude Code, Codex CLI, and Gemini via Pi

Open http://localhost:4567 to view the app through Layrr. Layrr also opens the browser automatically unless you pass --no-open.

3. Solve the UI problem in the browser

Choose the workflow based on what you are trying to fix:

• If a single element is the wrong size or position, select it and use visual editing.
• If the words are wrong, click the text and edit it inline.
• If a whole region needs work, draw an area around it and describe the change.
• If you have a target design, upload the image and explain what should match.

Apply the change, then inspect the updated app after your dev server reloads.

Common flags

layrr --port 3000
layrr --port 3000 --proxy-port 8888
layrr --port 3000 --agent codex
layrr --port 3000 ~/projects/my-app
layrr --configure-gemini

Use --port for the dev server Layrr should proxy. Pass a project path when you want Layrr to operate on a directory other than the current working directory.

Common problems

Layrr opens, but the app is not there

Your dev server may not be running, or Layrr may be pointed at the wrong port. Start the app first, then run:

npx layrr@latest --port 3000

Replace 3000 with the port your app uses.

Port 4567 is already in use

Choose a different proxy port:

npx layrr@latest --port 3000 --proxy-port 8888

Then open http://localhost:8888.

Layrr is editing the wrong directory

Run Layrr from the project root, or pass the directory explicitly:

npx layrr@latest --port 3000 ~/projects/my-app

Build from source

If you prefer to build locally:

git clone https://github.com/narnia-sh/layrr.git
cd layrr
pnpm install
pnpm build
node dist/cli.js --port 3000