Launch offer: use code LAUNCH20 for 20% off any single pack. See the packs

Lovable to Cursor or Claude Code: A Sync-Safe Handoff (Free Kit)

Published 2026-11-17 · 6 min read · by AgentKit Co

Lovable's Git sync lets you clone your project, edit it in Cursor, Claude Code or Codex, and push the result back into Lovable. The steps are short. The ways it goes wrong are not obvious: an agent that rebases main, a "quick test" that deletes real users, a service key that ends up in the browser bundle.

This page covers the handoff, then gives you a free kit that teaches your coding agent the same rules: an AGENTS.md, a CLAUDE.md, a Cursor rule, and a preflight script that checks the repo before you push.

Everything here was checked against Lovable's Git sync overview and GitHub sync docs on 2026-11-17. The script was tested with 24 cases on throwaway git repos (the test file is in the download). We have not run it against a paid Lovable project or on Windows, and Lovable changes quickly, so re-check the docs for anything you rely on.

Download free-lovable-handoff-kit.zip (MIT, bash + git, rules for Cursor / Claude Code / AGENTS.md tools, lovable-preflight.sh, test.sh)

The handoff in five steps

  1. Connect GitHub. In Lovable open Project settings → Git → GitHub and click Connect next to your workspace connection. Lovable creates a new repository (private by default) and starts two-way sync. It can't attach to a repo you already have.
  2. Wait for "in sync". Let any Lovable edit finish, then check the sync status card in the same settings page. Cloning before that gives you a stale copy.
  3. Clone and branch. Clone with the URL Lovable shows, open the folder in Cursor (or run claude / codex in it), and create a feature branch: git switch -c my-change.
  4. Run it. Lovable's docs say to check the README and package.json for what to install and which script starts the app. Use the package manager that matches the lockfile.
  5. Merge back. Push your branch, open a pull request into the synced branch and merge it. Lovable pulls the result. Then tell Lovable what changed so its next edit builds on your work.

Six rules your agent doesn't know

These come straight from Lovable's docs. Coding agents don't know any of them unless you write them down, which is what the rules files in the kit do.

  1. Lovable syncs one branch at a time, usually main. Commits on other branches don't appear until you merge them. Keep Lovable on that branch and do your work on a feature branch.
  2. Never force-push, rebase or squash synced commits. Lovable keeps its own copy of the branch. If you rewrite history, the next sync backs up Lovable's copy and replaces it with yours, and only the project owner can restore it. To undo, add a revert commit.
  3. Your local app uses the live backend. In a project with Lovable's built-in backend, the repo's .env carries values like VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY. Lovable's docs are blunt: records you create or delete locally change real data, and a Git branch does not give you a separate database. Use test accounts.
  4. VITE_ means public. Anything with that prefix is bundled into the code sent to the browser. Never put a service role key or any other secret in one.
  5. Backend files don't deploy themselves. Edge Functions in supabase/functions/ and migration files in supabase/migrations/ or drizzle/migrations/ sync as code, but Lovable doesn't deploy a changed function or run a new migration. Ask Lovable in chat to deploy, or run the SQL yourself.
  6. Newer apps can't call Lovable's connectors locally. Apps created from May 13, 2026 use TanStack Start, so server code runs on your machine, and connector and Lovable AI calls fail locally because their credentials stay with Lovable. Older React + Vite apps run those calls in Edge Functions, so they still work. If package.json lists @tanstack/react-start, you have the newer kind: test those calls in the Lovable preview and don't let the agent "fix" them by adding keys.

What the preflight script checks

Run ./lovable-preflight.sh (or ./lovable-preflight.sh develop if Lovable syncs another branch) before you push. It prints variable names, never values.

Check Result
You're on the synced branch WARN, with the git switch -c fix
Your branch is missing commits from the synced branch (rebased or stale) WARN: merge it in, don't rebase
@tanstack/react-start in package.json INFO: connector/AI calls fail locally by design
Lockfile INFO: which install command to use
VITE_ name containing SERVICE_ROLE, SECRET, PRIVATE, PASSWORD, SK_LIVE/SK_TEST FAIL (exit 1)
VITE_ name containing TOKEN or ending in _KEY (not PUBLISHABLE/ANON) WARN: OK only if the provider says it's public
VITE_SUPABASE_URL present WARN: local writes hit live data
.env.local committed to git FAIL
Changes under supabase/functions/ WARN: ask Lovable to deploy
New or changed migration files WARN: Lovable won't run them

Sample run on a feature branch with a leaked key:

OK    working on 'my-change', not the synced branch 'main'
OK    'my-change' contains all of origin/main (no rewritten history)
INFO  React + Vite app: connector and AI calls run in Edge Functions on your backend
INFO  lockfile: npm (npm install)
FAIL  .env: VITE_SUPABASE_SERVICE_ROLE_KEY has a public VITE_ prefix but looks like a secret (it would ship to every visitor's browser)
WARN  .env points at a Supabase backend: a local app reads and writes the SAME data as your published app. Use test accounts
---
preflight: 1 fail, 1 warn (synced branch: main)

The checks are name-based. A secret with an innocent name won't be caught, so treat a clean run as "nothing obvious", not "safe".

The rules files

AGENTS.md holds the full rules (Codex reads it, and so do Cursor and other AGENTS.md tools). CLAUDE.md is one line, @AGENTS.md, so Claude Code imports the same file instead of keeping a second copy. .cursor/rules/lovable-sync.mdc is a short always-on rule for Cursor that points at AGENTS.md. Edit the synced branch name in AGENTS.md if yours isn't main.

The last rule in AGENTS.md asks the agent to end with a one-line summary in the format Lovable's docs suggest pasting into chat: "I changed [files] outside Lovable to [change]. Keep [constraint] when making further edits." That chat message is a normal Lovable request, so it uses credits; editing locally does not.

Troubleshooting

  • Your commits don't show up in Lovable. You probably pushed to a branch other than the synced one. Merge into it, or switch the synced branch in Lovable's GitHub settings.
  • The card says GitHub is ahead. Lovable missed the push notification. Lovable's docs say to push any new commit to the synced branch, even an empty one (git commit --allow-empty -m "resync"), and Lovable syncs to the current state. Reconnect and Re-check don't pull commits.
  • A lovable-sync branch appeared. GitHub rejected Lovable's push, usually because of branch protection or a conflicting push. Review that branch and merge it with a merge commit, not a squash or rebase.
  • Don't delete the repo. Deleting it stops the sync. Renaming it, or your account, keeps sync running.

Related

Want rules for your whole stack, not just the sync? The AI Coding Agent Config Kit ($14) has AGENTS.md / CLAUDE.md / Cursor templates for 12 stacks, including Vite + React.

Sources: Lovable Git sync overview and Sync your Lovable project with GitHub (both checked 2026-11-17). AgentKit Co is not affiliated with Lovable, Cursor, Anthropic or OpenAI. This guide was written with AI assistance and checked against the pages above.

AI Coding Agent Config Kit

Instruction-file templates for 12 stacks and 12 prompts that write and audit them. 34-page PDF, $14.

Not ready to buy? Start with the free PDF.

Get 10 of our most-used prompts as a free PDF from Gumroad. You will be asked for your email so Gumroad can deliver it.

Keep reading

Agent Skills (SKILL.md) Explained: Formats, Folders and SafetyWhat an Agent Skill is, how SKILL.md works, which folders Claude Code, Codex, Cursor and Copilot read, and how to write and vet one. Checked on 2026-10-17.4 min readAGENTS.md Examples: 7 Copy-Paste Files for Real Projects (2026)Seven AGENTS.md examples to copy: Next.js, Python API, Go, a monorepo with nested files, a global ~/.codex file, an override and review rules.7 min readWhat Is an AI Agent? Plain-English Guide for BeginnersWhat an AI agent is, how it differs from a chatbot or automation, and the four building blocks every agent has. No jargon.4 min read