overleaf-sync-now

Stops Claude Code and Codex CLI from silently overwriting your Overleaf web edits with a stale local Dropbox copy.

The failure mode

You write a paper in Overleaf with Dropbox sync enabled. You edit on overleaf.com from another device, then come back to your laptop and ask Claude Code (or Codex CLI) to keep working on the paper. The AI agent reads the local .tex file — but Overleaf only pushes web edits to Dropbox every 10–20 minutes, so the local copy is stale. The AI proceeds to edit the stale file and saves it back, silently overwriting your fresh web edits. The tool call reports success. Paragraphs you wrote on the web vanish.

overleaf-sync-now is an agent skill (plus a CLI and a Claude Code PreToolUse hook) that closes this gap. Before every AI Read / Edit / Write of a .tex / .bib / .cls / .sty / .bst file under Apps/Overleaf/, it probes Overleaf's version history and pulls down anything new — without changing your existing Dropbox setup, so cross-device sync still works exactly as before.

Is this for you?

• ✅ You write papers in Overleaf Premium with Dropbox sync enabled (Dropbox/Apps/Overleaf/<project>/)
• ✅ You edit .tex files locally with Claude Code or Codex CLI
• ✅ You also edit on overleaf.com sometimes — from another device, in a browser, or with collaborators

If you only ever edit locally or only ever edit on the web, your local copy is never stale and you don't need this. Same if you don't use Dropbox or AI agents.

Install

In Claude Code or Codex CLI, paste this prompt:

Install overleaf-sync-now from https://github.com/hanlulong/overleaf-sync-now using uv tool install, then run `overleaf-sync-now install`.

The agent installs everything and runs setup. Restart the agent afterward (/exit then claude in Claude Code; equivalent in Codex).

On Windows with Chrome 130 or later, also run overleaf-sync-now login once — Chrome's new App-Bound Encryption blocks the silent cookie path. Details.

curl -LsSf https://astral.sh/uv/install.sh | sh && \
  export PATH="$HOME/.local/bin:$PATH" && \
  uv tool install --from git+https://github.com/hanlulong/overleaf-sync-now overleaf-sync-now && \
  overleaf-sync-now install

irm https://astral.sh/uv/install.ps1 | iex
$env:PATH = "$env:USERPROFILE\.local\bin;$env:PATH"
uv tool install --from git+https://github.com/hanlulong/overleaf-sync-now overleaf-sync-now
overleaf-sync-now install

Verify

After restart, edit any .tex file under Dropbox/Apps/Overleaf/<project>/ — the hook fires automatically. Or check manually:

overleaf-sync-now status   # cookie + linked project
overleaf-sync-now sync     # trigger a sync, print latency

Why

You use Dropbox with Overleaf because it gives you free multi-device sync — an edit on your laptop is instantly readable on your desktop, your iPad, and your collaborator's machine. AI agents like Claude Code and Codex CLI plug into that setup naturally: they just read and write the local .tex file like you do.

The problem: Overleaf's Dropbox sync polls the Overleaf-web → local direction every 10–20 minutes. So if you've edited the paper on overleaf.com and then ask the AI to keep working, it reads a stale local file and silently overwrites the changes you just made — restoring deleted paragraphs, undoing fresh edits, all while reporting a successful tool call.

overleaf-sync-now checks Overleaf for fresh content immediately before each AI edit and pulls only what changed. Dropbox keeps doing its multi-device job; the AI loop stops clobbering your work. Nothing else in your setup changes.

When nothing changed on the Overleaf side, the hot path is ~0.3–1 s (a single read-only probe, no zip download). When something changed, the tool downloads the project zip once and writes only the files whose content differs from local — typically 5–10 s for a normal paper.

How it works

1. The PreToolUse hook intercepts every Read / Edit / Write / MultiEdit of .tex / .bib / .cls / .sty / .bst files. Other tools and other file types pass through.
2. Auto-link maps …/Apps/Overleaf/<name>/ to its Overleaf project ID via a 24-hour-cached project list. On a unique match the tool drops a tiny .overleaf-project marker into the folder so future resolution is deterministic — no manual setup needed. Override or pre-seed it with overleaf-sync-now link <id> when names differ or two projects share a name.
3. Resolver safety net (since 0.3.0): the cached project list keeps trashed/archived flags, lastUpdated, and ownerId. Trashed and archived projects are filtered out of auto-link, and if two living projects still share a name the tool refuses to guess — it lists the candidates and asks you to pick. A sync-time fingerprint check warns if the linked project's recent Dropbox-origin updates touch files not present locally (the "I linked the wrong project" smoke detector).
4. Version-match probe: GET /project/<id>/updates returns Overleaf's history (fromV / toV / changed pathnames / origin). The tool caches the latest toV per project.
   • Latest toV matches cached → skip, no download.
   • Updates exist but are all Dropbox-origin (echoes of our own local saves round-tripping through Dropbox) → skip, no download.
   • A web-origin update exists → GET /project/<id>/download/zip and extract only the changed pathnames, hash-compared so unchanged files aren't rewritten.
5. Data-safety guard: extraction never overwrites a local file modified in the last 30 seconds — protects an in-progress local save that hasn't yet propagated Dropbox → Overleaf. Override with sync --force.
6. Debounce: 30 s per project. A flurry of AI edits share one probe.

For deeper details, see docs/architecture.md.

Subcommands

overleaf-sync-now --version                              # print package version
overleaf-sync-now install                                # one-shot setup (idempotent)
overleaf-sync-now login                                  # browser-assisted login (Chrome 130+ Windows)
overleaf-sync-now setup                                  # auth wizard (auto-detect from existing browsers)
overleaf-sync-now save-cookie <value>                    # paste a cookie value directly (last-resort)
overleaf-sync-now sync [folder] [--force]                # refresh against Overleaf; --force re-extracts
overleaf-sync-now status [folder] [--quick]              # cookie validity + linked project (source, name, trashed/archived flags, lastUpdated, cached toV)
overleaf-sync-now projects [--refresh]                   # list projects with NAME | PROJECT_ID | FLAGS (T/A/DUP) | LAST_UPDATED, sorted by recency
overleaf-sync-now doctor [folder]                        # full diagnostic, including a /updates probe
overleaf-sync-now link <id> .                            # override auto-link with a marker file (warns if id is trashed/archived)
overleaf-sync-now uninstall                              # remove skill + hook (keeps cookies)

sync and status default to the current directory. Run overleaf-sync-now --help for full usage.

Documentation

Related projects

The Overleaf-AI integration space is crowded. Each of these solves a different slice of the problem:

overleaf-sync-now is the only tool that keeps Dropbox (so all your devices and collaborators stay in sync the way they already do) and fires automatically (so the AI agent loop never reads a stale file). Smaller, narrower, invisible.

License

MIT

Credits

Created by Lu Han. Published by OpenEcon.ai.

If this saved you time, a ⭐ on the repo helps other researchers find it.