# Overleap > Bidirectional real-time sync between an Overleaf project and a local directory using the `overleap` Node.js CLI. Use when the user mentions Overleaf, overleap, "sync my Overleaf project", "edit Overleaf locally", "pull / push Overleaf", "compile Overleaf to PDF from CLI", or asks Claude to edit `.tex` files that should reflect on Overleaf in real time. Also use when the user wants to set up or re… - **Type:** Skill - **Install:** `agentstack add skill-axect-skills-overleap` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Axect](https://agentstack.voostack.com/s/axect) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Axect](https://github.com/Axect) - **Source:** https://github.com/Axect/skills/tree/main/overleap ## Install ```sh agentstack add skill-axect-skills-overleap ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # overleap Bidirectional real-time sync between an Overleaf project and a local directory via the `overleap` CLI (Node.js, [github.com/Axect/overleap](https://github.com/Axect/overleap)). `overleap` connects to Overleaf with the same Socket.IO + OT protocol the browser editor uses. Local edits are streamed to the server as OT operations; remote edits land on disk through atomic writes. Once a project is just local files, **anything that can edit a file can edit Overleaf** — Neovim, VS Code, scripts, and Claude. ## Trigger conditions Invoke this skill when the user says any of: - "sync my Overleaf project" / "start overleap" / "edit Overleaf locally" → `overleap sync` workflow (see **Sync workflow**) - "list my Overleaf projects" / "what projects do I have on Overleaf" → `overleap projects` - "compile this on Overleaf" / "build the PDF via Overleaf" / "compile this paper" *while in an overleap-synced directory* → `overleap compile` (do **not** run `pdflatex` / `latexmk` locally inside the sync dir — see **Path & file rules** below for why) - "set up overleap" / "configure overleap" / "save my Overleaf cookie" / `overleap` exits with `OVERLEAF_COOKIE is required` → **Setup flow** - "refresh the Overleaf cookie" / "my Overleaf session expired" → **Cookie refresh** in `references/cookie-setup.md` - The user asks Claude to edit `.tex` / `.bib` / `.sty` files in a directory that already has `.env` with `OVERLEAF_COOKIE` → assume sync is the intended flow; check whether a sync daemon is already running before starting one ## Prerequisites 1. **Node.js >= 18** and **git** (the dependency `socket.io-client` is fetched from a GitHub fork). ```bash node --version # must be >= 18 git --version ``` 2. **`overleap` CLI installed**. Verify: ```bash command -v overleap && overleap --help | head -5 ``` If missing, install globally: ```bash npm install -g overleap ``` Or, if the user has a local checkout (e.g. `~/Documents/Project/AI_Project/overleap`), run from there with `node bin/overleap.js ...`. 3. **A valid Overleaf session cookie** in one of: - `OVERLEAF_COOKIE` environment variable - `.env` file in the working directory or in `--dir` (key: `OVERLEAF_COOKIE`) - `--cookie` / `-c` flag (least preferred — appears in process listings) See `references/cookie-setup.md` for how the user extracts the cookie from the browser. ## Setup flow (skill-orchestrated) Run this when the user wants to start using overleap on a new machine, in a new project directory, or after their session expires. 1. **Verify prerequisites** (Node 18+, git, `overleap` on PATH). If any is missing, tell the user the exact install command and stop. 2. **Decide the local sync directory**. Prefer the user's chosen folder for the Overleaf project (e.g. `~/Papers/quantum-draft`). Confirm before creating it. 3. **Create the `.env` file** inside that directory. Ask the user to paste their cookie with this exact caveat: > Your Overleaf session cookie grants full access to your account. It will be saved at `/.env`. Only paste it here if you trust this terminal and session transcript. Add `.env` to `.gitignore` immediately. Get it from browser DevTools → Application → Cookies → overleaf.com → copy the full cookie string (or just `overleaf_session2`). Detailed steps: see `references/cookie-setup.md`. 4. After the user replies with the cookie, write the file with `0600` permissions and append `.env` to `.gitignore`: ```bash bash scripts/init_env.sh ``` The script reads the cookie from stdin (so the value never appears in argv / shell history) and refuses to overwrite an existing `.env` unless `--force` is passed. 5. **Smoke-test** with a non-destructive call: ```bash cd && overleap projects ``` On success, you'll see a numbered project list. On failure with `OVERLEAF_COOKIE is required` or auth errors, surface the message verbatim and offer to re-run setup. **Do not** echo the cookie back, log it, or paste it into commit messages. If you must reference it, say "the cookie you provided". **Do not** run setup unprompted. Triggers are: explicit user request, or a blocked operation that returned `OVERLEAF_COOKIE is required` / `401` / `403`. ## Commands | Command | What it does | Long-running? | |---|---|---| | `overleap projects` | List projects available to the logged-in account | No, returns immediately | | `overleap sync` | Start bidirectional real-time sync daemon | **Yes — never exits until Ctrl+C** | | `overleap compile` | Trigger remote LaTeX compilation, download `output.pdf` | No (waits for the compile to finish, ~5–60s) | ### Common flags | Flag | Env var | Meaning | |---|---|---| | `--project`, `-p` | `OVERLEAF_PROJECT_ID` | Project number (from `projects` list), fuzzy name match, or 24-char Overleaf ID | | `--dir`, `-d` | `OVERLEAF_DIR` | Local directory (default: cwd) | | `--cookie`, `-c` | `OVERLEAF_COOKIE` | Session cookie (prefer `.env` over `-c`) | | `--url`, `-u` | `OVERLEAF_URL` | Server URL (default: `https://www.overleaf.com`) | Project selection: - `-p 3` — pick the 3rd project from the list - `-p "quantum"` — fuzzy match by name (must be unique; otherwise overleap re-prompts) - `-p 64a1b2c3d4e5f6...` — direct 24-hex Overleaf project ID - omit `-p` — interactive numbered list (requires a TTY) ## Sync workflow `overleap sync` is a **long-running daemon** that connects via Socket.IO and never exits until you signal it (`SIGINT` / `SIGTERM`). This has consequences for how Claude should run it. **Never invoke `overleap sync` as a foreground Bash call from Claude** — the tool will block until timeout, you cannot do further work, and if/when the harness times out the daemon is killed mid-edit. Pick **one** of the patterns below depending on the user's setup. Default to (1) when in doubt, because it gives the user the most control. ### Pattern 1 — User runs sync in their own terminal (recommended default) Tell the user the exact command to run in a separate terminal pane and wait for them to confirm it's running: ```bash cd overleap sync -p ``` While that daemon is running, Claude edits `.tex` files in `` directly with `Edit` / `Write`. Each save propagates to Overleaf within ~150 ms (debounced). To stop, the user hits Ctrl+C in that terminal. This is the safest pattern: the user sees the live log (connection state, OT acks, conflict resyncs) and can intervene immediately. ### Pattern 2 — Run sync under `pueue` (per the user's global rule) The user's `CLAUDE.md` already mandates `pueue` for long-running tasks. For overleap, create a per-project group and queue the daemon: ```bash # One-time, per project pueue group add overleap- # Start the daemon pueue add -g overleap- -- bash -c 'cd && overleap sync -p ' # Inspect live log pueue log -f # Stop cleanly (SIGINT) pueue kill -s SIGINT ``` Use this when the user explicitly asks for a background daemon, or when sync should outlive the current shell. **Always** confirm with the user before queueing — and never kill a pueue task belonging to another project (per the global rule). ### Pattern 3 — Background via Claude's `run_in_background` Acceptable for short demos within a single Claude session, but the daemon dies when the session ends. Only use when the user explicitly wants it: ```bash # Bash tool with run_in_background: true cd && overleap sync -p ``` Always tell the user this daemon is tied to the session lifetime. ### Editing while sync is running - Edit files normally. `overleap` debounces local writes (~150 ms) and only sends OT ops once content is stable, so rapid `Edit` calls are safe. - For new files: just create them in ``. They auto-upload (text → as Overleaf docs, binary → multipart upload). - For deletes: `rm` in ``. Server-side delete is sent. - For binary files (images, PDFs included as figures), uploads are throttled to 3 concurrent and retried once on transient HTTP errors. - If the daemon log shows `Disconnected: `, it auto-reconnects with exponential backoff (1 → 30 s). No manual action needed unless the cookie expired (see cookie refresh in `references/cookie-setup.md`). ### Stopping sync - Pattern 1: user hits Ctrl+C in their terminal. - Pattern 2: `pueue kill -s SIGINT `. - Pattern 3: `KillBash` on the background shell (or end the session). Never `kill -9` — the daemon needs SIGINT/SIGTERM to send `leaveDoc` notifications, clear debounce timers, stop the watcher, and disconnect the socket cleanly. SIGKILL leaks inotify watches and leaves the server thinking you're still connected. Note that even SIGINT does not force-flush in-flight edits — a change still inside the 150 ms debounce window at shutdown is dropped, so save and wait ~200 ms before stopping if you care about the last keystroke. ## Compile workflow (`overleap compile`) One-shot remote LaTeX compile + PDF download. Safe to run as a regular foreground Bash call. ```bash cd && overleap compile -p ``` - Output is written to `/output.pdf` (overwrites any existing file with the same name). - If compilation fails server-side, the script prints `[compile] Compilation failed:` and points to the log. Surface the message verbatim and offer to inspect the log via the Overleaf web UI. - `compile` does **not** require sync to be running — it goes through the REST endpoint with the cookie + CSRF token. - **Always prefer `overleap compile` over local `pdflatex` / `latexmk` / `bibtex` when the directory is an overleap sync target.** Local compile leaks `.aux` / `.log` / `.bbl` / `.fls` / `.fdb_latexmk` / `.synctex.gz` artifacts back to Overleaf — see Path & file rules. ## Project listing (`overleap projects`) Safe, one-shot, non-destructive. Useful as a connectivity / auth smoke test: ```bash cd && overleap projects ``` Output is a numbered table of `name [accessLevel] lastUpdated`. The number is what `-p N` consumes. ## Path & file rules - `overleap` always operates relative to `--dir` (or cwd). Never run sync from `~` or any directory containing unrelated files — it will try to upload everything that's not in `IGNORE_PATTERNS`. - The watcher ignores common noise (`.git/`, `node_modules/`, dotfiles handled by chokidar defaults, plus the patterns in `overleap/src/constants.js`). Still, **start sync in a clean directory** dedicated to that one Overleaf project. - Do not put `.env` (with the cookie) in the same directory committed to git without first ensuring it's in `.gitignore`. The setup script does this automatically. - **Do not run local LaTeX compilation inside the sync directory.** `pdflatex` / `latexmk` / `bibtex` / `biber` / `xelatex` produce `.aux`, `.log`, `.bbl`, `.bcf`, `.blg`, `.toc`, `.out`, `.fls`, `.fdb_latexmk`, `.synctex.gz`, and `.pdf` artifacts. `overleap`'s `IGNORE_PATTERNS` does **not** filter any of these — they will all be uploaded to Overleaf as if you'd added them to the project. Real consequences seen in the past: duplicate bibliography rendering on the server, conflicting compile state, noisy collaborator diffs, accidental `output.pdf` overwrite. Use **`overleap compile`** for PDF generation (server-side, returns `output.pdf` only — see Compile workflow above), or **copy `.tex` files to a separate scratch directory** for local compile testing and never touch them in the sync dir while compiling. If you've already leaked artifacts, clean them up via the Overleaf web UI's file panel or, if the project is git-tracked, `git rm` and let overleap propagate the deletes. ## Failure modes & how to react | Symptom | Likely cause | Action | |---|---|---| | `OVERLEAF_COOKIE is required` | No cookie in env, `.env`, or flag | Run setup flow | | `HTTP 401` / `HTTP 403` from `projects` or compile | Cookie expired or revoked | Re-extract cookie from browser, re-run `init_env.sh --force` | | `Disconnected: ...` in sync log, repeating | Network blip or session expired | If brief, ignore — auto-reconnect handles it. If persistent, check cookie freshness. | | `inotify watcher limit reached` | Linux `fs.inotify.max_user_watches` too low | Daemon prints the exact `sysctl` command — surface it to the user; they need sudo to apply | | Compile fails with no PDF | LaTeX error on Overleaf side | Open the project in the browser and inspect the log; overleap surfaces only `success/failure` | | `Multiple matches for "":` followed by an interactive prompt | Fuzzy `-p` match was ambiguous; in a non-TTY context the prompt fails immediately with `Input stream closed` or `Invalid selection` | Re-run with a more specific name, the project number from `overleap projects`, or the 24-char Overleaf ID | | Local file overwritten unexpectedly | Two writers (Claude + collaborator) racing | Sync engine uses OT to merge, but if a collaborator deletes a file you just created, the server wins. Restore from git or Overleaf history. | | Mysterious duplicate bibliography on Overleaf, or `.aux` / `.log` / `.bbl` / `.fls` / `.fdb_latexmk` files appearing in the project | Local LaTeX compile (`pdflatex`, `latexmk`, etc.) was run inside the sync directory and the build artifacts uploaded | Stop the local compile. Move it to a scratch directory outside `--dir`. Clean up the leaked artifacts on Overleaf via the web UI's file panel (or `git rm` if the project is git-tracked). For PDF output, prefer `overleap compile` instead. | For deeper context on the protocol, OT version tracking, and edge cases the upstream project has fixed, see `references/sync-internals.md`. ## Related references - `references/cookie-setup.md` — step-by-step browser instructions for extracting / refreshing `OVERLEAF_COOKIE`, including which cookie value(s) actually matter - `references/sync-internals.md` — what the sync daemon does on the wire (OT, debouncing, binary uploads, reconnection), useful for diagnosing weird sync behavior - `references/long-running-patterns.md` — concrete recipes for running `overleap sync` under `pueue`, in `tmux`, or in the background, with stop/restart commands ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Axect](https://github.com/Axect) - **Source:** [Axect/skills](https://github.com/Axect/skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** yes *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-axect-skills-overleap - Seller: https://agentstack.voostack.com/s/axect - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.