Lovable to Cursor or Claude Code: A Sync-Safe Handoff (Free Kit)
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
- 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.
- 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.
- Clone and branch. Clone with the URL Lovable shows, open the folder in Cursor (or run
claude/codexin it), and create a feature branch:git switch -c my-change. - Run it. Lovable's docs say to check the README and
package.jsonfor what to install and which script starts the app. Use the package manager that matches the lockfile. - 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.
- 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. - 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.
- Your local app uses the live backend. In a project with Lovable's built-in backend, the repo's
.envcarries values likeVITE_SUPABASE_URLandVITE_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. 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.- Backend files don't deploy themselves. Edge Functions in
supabase/functions/and migration files insupabase/migrations/ordrizzle/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. - 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.jsonlists@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-syncbranch 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
- AGENTS.md examples and how to write one
- Cursor rules examples and CLAUDE.md examples
- How to review AI-generated pull requests, useful before you merge into the synced branch
- Cursor hooks examples, if you want a hook that blocks risky shell commands too
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.