lovagentic

lovagentic is a browser-first operator CLI for steering Lovable through stable, user-owned surfaces.

It focuses on:

• official Lovable URLs
• Playwright automation against the Lovable web UI
• persistent browser profiles with real Lovable sessions
• explicit verification and persistence checks after write actions

It deliberately avoids:

• patching or injecting into Lovable.app
• depending on private desktop IPC
• treating undocumented backend endpoints as the primary interface

Status

This repository is production-minded, but still pragmatic:

• stable enough for real operator workflows
• honest about Lovable UI drift and verification challenges
• biased toward explicit failures instead of false success

If Lovable or Cloudflare triggers an interactive verification, headed runs are still the reliable path.

Roadmap

Native MCP support coming next week — early access by Lovable.

Why this repo exists

Lovable's desktop app is useful, but a user-owned CLI is much easier to reason about when it stays on durable surfaces:

1. public creation URLs
2. the authenticated Lovable web UI
3. published preview and live URLs

That keeps the repo maintainable and avoids coupling to private desktop internals.

Features

• Lovable session bootstrap and profile seeding
• dashboard project and workspace listing
• project creation from official build URLs
• prompt submission with server-side acceptance checks
• build / plan mode switching
• prompt auto-splitting for large requests
• queue pause detection and optional auto-resume
• question-card reading and answering
• proposal action discovery and clicking
• runtime error inspection and Try to fix
• findings extraction from Lovable's security pane
• wait-for-idle orchestration
• preview verification with screenshots, layout heuristics, console checks, and text assertions
• publish, publish settings, and domain management
• toolbar, project settings, workspace settings, git, code, knowledge, and speed surfaces
• iterative fidelity-loop repair flows

Repository layout

src/
  cli.js              Commander entrypoint and command wiring
  browser.js          Playwright-driven Lovable surface automation
  orchestration.js    Prompt splitting, idle-state logic, orchestration helpers
  config.js           Paths and defaults
  profile.js          Session/profile copy helpers
  url.js              Build/create URL helpers

test/
  *.test.js           Focused regression tests for orchestration and browser helpers

skills/
  lovagentic/        Repo-local OpenClaw skill

Supporting docs:

• AGENTS.md for agent-oriented operating guidance
• CONTRIBUTING.md for contributor workflow
• SECURITY.md for secret-handling and reporting expectations
• CHANGELOG.md for release history
• docs/commands.md for the generated CLI reference
• docs/releases.md for the release process

Requirements

• macOS recommended
• Node.js 20+
• npm
• Playwright Chromium installed
• a valid Lovable account and session on the machine where the CLI runs

Install

npm install
npx playwright install chromium

Quick start

Inspect the local environment:

npm run doctor

Login once into the CLI-managed browser profile:

npm run start -- login

Create a new project:

npm run start -- create "Build a marketing site for a solar company"

Prompt an existing project:

npm run start -- prompt "https://lovable.dev/projects/your-project" \
  "Add a testimonials section and tighten the mobile spacing."

Wait until Lovable is really idle:

npm run start -- wait-for-idle "https://lovable.dev/projects/your-project" \
  --profile-dir /tmp/lovagentic-profile \
  --seed-desktop-session \
  --headless \
  --json

Verify the preview:

npm run start -- verify "https://lovable.dev/projects/your-project" \
  --profile-dir /tmp/lovagentic-profile \
  --seed-desktop-session

Authentication and session model

The CLI is only useful when the Playwright profile contains a real Lovable session.

Preferred auth paths:

1. npm run start -- login
2. npm run start -- import-desktop-session
3. --seed-desktop-session on supported commands

Important constraints:

• desktop-profile import is best-effort
• headed runs are safer when interactive verification is likely
• headless runs are practical, not guaranteed

Core command groups

Bootstrap and session

Prompt orchestration

Project and publish surfaces

Run npm run help or npm run start -- --help for the full command list.

Common workflows

Create and publish a throwaway smoke project

npm run start -- create "Build a simple static smoke page with one heading and one CTA" \
  --profile-dir /tmp/lovagentic-smoke \
  --seed-desktop-session \
  --workspace "Tobi's Lovable" \
  --headless

npm run start -- publish "https://lovable.dev/projects/your-project" \
  --profile-dir /tmp/lovagentic-smoke \
  --seed-desktop-session \
  --headless

Send a long prompt safely

Large prompts are auto-split by default:

npm run start -- prompt "https://lovable.dev/projects/your-project" \
  "$(cat ./long-prompt.txt)" \
  --profile-dir /tmp/lovagentic-profile \
  --seed-desktop-session \
  --mode plan

If you deliberately keep a large prompt in a single Lovable turn with --no-auto-split, the CLI now gives larger prompts more time and can rely on server acceptance plus reload persistence before failing.

Run a plan approval flow

npm run start -- chat-loop "https://lovable.dev/projects/your-project" \
  "Outline the next changes before touching code." \
  --profile-dir /tmp/lovagentic-profile \
  --seed-desktop-session \
  --mode plan \
  --action "Approve"

Prompt and verify immediately

npm run start -- prompt "https://lovable.dev/projects/your-project" \
  "Add a testimonials section." \
  --profile-dir /tmp/lovagentic-profile \
  --seed-desktop-session \
  --verify \
  --expect-text "Testimonials" \
  --forbid-text "404"

Safety model

lovagentic is intentionally conservative:

• it prefers browser-observable state over guessed internal APIs
• it checks for server-side chat acceptance where possible
• it re-checks persistence after reload for write paths
• it distinguishes idle, paused queue, open questions, and error states
• it refuses to silently treat UI-local state as success

Recommended testing pattern:

--profile-dir /tmp/lovagentic-<task-name>
--seed-desktop-session

Prefer throwaway projects for:

• prompt regression checks
• queue handling tests
• domain and publish experiments
• anything that mutates content or settings

Known limitations

• interactive verification challenges can still block headless flows
• visual verification is screenshot/runtime-based, not golden-image diffing
• domain purchase and registrar flows are not automated
• some Lovable surfaces can drift and need selector maintenance
• knowledge writes are guarded and fail if Lovable does not persist them after reload

Development

Run the local checks:

npm test
npm run check

Core scripts:

GitHub Actions CI runs npm ci, installs Playwright Chromium, and executes npm run check. Dependabot keeps npm and GitHub Actions dependencies moving weekly.

Design constraints

When extending this repo:

• preserve the stable-surfaces-only design
• prefer DOM/state detection over brittle CSS selectors
• keep new commands idempotent when practical
• verify real persistence after reload
• document user-facing behavior changes in this README

Related files

• AGENTS.md
• skills/lovagentic/SKILL.md
• docs/commands.md