overleaf-remote ยท diff
git:20261014.a1536cc to git:20261014.070cb90
72 added, 54 removed. Audit A to A.
---
name: overleaf-remote
- description: Install and use the bundled olcli to create, inspect, edit, precisely patch, organize, upload to, download from, and compile Overleaf projects without maintaining a local pull/push checkout. Use for Overleaf CLI setup, session-cookie authentication, direct remote file operations, or diagnosing olcli access and synchronization problems.
+ description: Install and use the bundled olcli to read, inspect, create, edit, precisely patch, organize, upload to, download from, and compile Overleaf projects without maintaining a local pull/push checkout. Prefer the persistent live session for reading and editing remote documents. Use for Overleaf CLI setup, session-cookie authentication, direct remote file operations, or diagnosing olcli access and synchronization problems.
---
# Overleaf Remote
+ ## Start here: is a live session running?
+
+ `olcli live` is the default interface to a project, for reading as much as for
+ editing. **Before anything else, check whether a session already covers the
+ project** (`olcli-live ls` on macOS/Linux, or `tmux ls`):
+
+ - **If one is running, use it for everything.** `{"op":"ls"}` lists the project,
+ `{"op":"read","path":...}` reads a document, and the edit operations below
+ change it.
+ - **If none is running, start one** before reaching for one-shot commands:
+ `olcli live "My Paper"`, or a tmux window via `scripts/run-live.sh` so it
+ outlives the terminal. It costs a few seconds and is reused for every later
+ step.
+
+ Reach for `olcli download` only when you need the bytes on local disk: a ZIP, a
+ binary, or compile output.
+
+ The session holds each joined document's current text and version, so it answers
+ a read without a download and can tell you whether what you last read is still
+ current. `{"op":"stat"}` reports whether the local copy is stale, and
+ `remoteChanged` flags an edit from another connection. A full read is mirrored
+ under `~/.olcli/live/<projectId>/`, and `{"op":"mirror","intervalMs":1000}` keeps
+ it current. The mirror is read-only: never edit those files, and never upload
+ them back; change content only through `replace`/`insert`/`append`.
+
+ ## How edits work
+
Use the bundled olcli build for direct Overleaf operations. Prefer precise
remote commands (`replace`, `insert`, `append`, `prepend`, `write`, `mkdir`,
- and `upload --to`) over maintaining a continuously synchronized local copy when
- the user wants changes made directly on Overleaf. `edit` is not a general editor:
- it only fills an empty document, and `write` only creates a document or fills an
- empty one. Whole-document replacement is refused everywhere else, so plan every
- change as a targeted operation against the document's live content.
+ and `upload --to`) over a bidirectional pull/push checkout. The live mirror is
+ not that: it is one-way and read-only. `edit` is not a general editor: it only
+ fills an empty document, and `write` only creates a document or fills an empty
+ one. Whole-document replacement is refused everywhere else, so plan every change
+ as a targeted operation against the document's live content.
- For multiple edits in one working session, prefer `olcli live`: it keeps one
- Overleaf collaboration WebSocket open, joins text documents lazily, and sends
- small versioned OT insert/delete operations instead of downloading and
- re-uploading whole files. It tracks collaborator updates and safely rejoins a
- document after a race. `auto` mode falls back to verified HTTP replacement only
- when the failure happened before an OT write was sent; uncertain writes are
- never retried blindly. Use `--transport ot` to require OT or `--transport http`
- to diagnose compatibility with older self-hosted instances.
+ `olcli live` keeps one Overleaf collaboration WebSocket open, joins text
+ documents lazily, and sends small versioned OT insert/delete operations instead
+ of downloading and re-uploading whole files. It tracks collaborator updates and
+ safely rejoins a document after a race. `auto` mode falls back to verified HTTP
+ replacement only when the failure happened before an OT write was sent;
+ uncertain writes are never retried blindly. Use `--transport ot` to require OT
+ or `--transport http` to diagnose compatibility with older self-hosted
+ instances.
- On macOS or Linux with `tmux`, keep that session alive in tmux instead of
- starting a new `olcli live` for every request: one tmux window per project. Use
- the bundled `scripts/run-live.sh` to run it (it restarts the session if it
- exits, since tmux has no restart-on-crash of its own) and `scripts/olcli-live`
- to send operations and wait for their replies. A tmux server is a single
- per-user process, so several terminals and several agent sessions share one
- connection. Never drive one window from two writers at once; the JSON replies
- interleave and you can no longer tell which reply belongs to which operation.
+ ## Hosting the session
- A live session can also read: `{"op":"read","path":...}` returns a document's
- current text without a download, either written to a local mirror under
- `~/.olcli/live/<projectId>/` or, with `offset`/`limit`, as a bounded inline
- slice. `{"op":"ls"}` lists the project and `{"op":"stat"}` reports whether the
- local copy is current. `{"op":"mirror","intervalMs":1000}` keeps those copies
- in sync, pulling the remote down whenever it changes, and reports
- `remoteChanged` when another connection edited a document since your last read.
- The mirror is read-only: never edit those files, and never upload them back;
- change content only through `replace`/`insert`/`append`.
+ On macOS or Linux with `tmux`, keep the session alive rather than starting a new
+ `olcli live` for every request: one tmux window per project, started with
+ `scripts/run-live.sh` (it restarts the session if it exits, since tmux has no
+ restart-on-crash of its own) and driven with `scripts/olcli-live send`, which
+ waits for each reply. A tmux server is a single per-user process, so several
+ terminals and several agent sessions share one connection. Never drive one
+ window from two writers at once; the replies interleave and you can no longer
+ tell which reply belongs to which operation.
- This persistent-session workflow is macOS and Linux only. Both helpers are bash
- scripts, there is no PowerShell equivalent, and the installer deliberately does
- not place them on PATH on Windows. On Windows, start `olcli live` per request
- and use the one-shot commands for single edits.
+ Windows is out of scope for this: both helpers are bash scripts with no
+ PowerShell twin, and the installer deliberately does not place them on PATH. On
+ Windows, start `olcli live` per request and use the one-shot commands for single
+ edits.
## Route the task
+ - For anything on a project, start from the live session (see *Start here*); its
+ operations are in
+ [references/commands.md](references/commands.md#persistent-real-time-session).
- For first-time installation, authentication, or instructions for obtaining
the Overleaf cookie on macOS or Windows, read
[references/setup-and-cookie.md](references/setup-and-cookie.md) completely.
- For project, file, editing, upload, compile, and verification commands, read
[references/commands.md](references/commands.md) completely.
- When authentication, PATH, folder resolution, upload, compilation, or content
verification fails, read
[references/troubleshooting.md](references/troubleshooting.md) completely.
## Operating rules
1. Treat `overleaf_session2` as a password. Never echo it, quote it in a report,
commit it, place it in the Skill, or expose it in process listings when a
hidden prompt is available.
2. Authentication permits access; it does not by itself authorize creating,
editing, deleting, renaming, or compiling a project. Confirm that the user's
request covers the intended remote mutation.
- 3. Never edit from a stale copy. Compute every change against the document's
+ 3. Default to the live session, for reads as well as writes (see *Start here*).
+ Do not read a document with `olcli download` while a session is running: it
+ wastes a round trip and throws away the session's record of whether that
+ content is current.
+ 4. Never edit from a stale copy. Compute every change against the document's
current remote content. Do not download a file, edit it locally, and upload
it back; do not reuse content read earlier in this conversation, in a
previous session, or from a local checkout. Re-read first. `olcli live`
follows collaborator updates as they arrive, and the one-shot commands
re-read immediately before writing. A base that was not freshly read may
already be superseded by someone else's text.
- 4. Never replace a whole document unless it is empty. `edit`, `write`, and
+ 5. Never replace a whole document unless it is empty. `edit`, `write`, and
`upload --to` refuse to overwrite a non-empty text document, because a
wholesale write silently discards everything a collaborator added since that
content was read. Express the change as targeted operations (`replace`,
`insert`, `append`, `prepend`) instead. Delete and recreate a file only when
the user has explicitly asked for a full rewrite.
- 5. Resolve the exact project and remote path before mutation. Prefer a project
+ 6. Resolve the exact project and remote path before mutation. Prefer a project
ID when names are ambiguous.
- 6. Use `replace` for an exact, unique change. It refuses multiple matches unless
+ 7. Use `replace` for an exact, unique change. It refuses multiple matches unless
`--all` is explicit. Use `insert` with a stable anchor and
`--occurrence <n>` when the anchor repeats.
- 7. Use `write` to create a text document or fill an empty one, `mkdir` for
+ 8. Use `write` to create a text document or fill an empty one, `mkdir` for
folders, and `upload --to` for images, PDFs, bibliographies, archives, or
other new files.
- 8. Preserve the built-in versioned OT acknowledgement or HTTP read-after-write verification. For binary uploads,
- download to a temporary file and compare hashes or bytes when correctness
- matters.
- 9. Do not start a pull/push daemon unless the user explicitly asks for ongoing
- synchronization. The direct commands are designed to avoid that workflow.
- 10. After repeated authentication failures, ask the user to refresh the cookie;
+ 9. Preserve the built-in versioned OT acknowledgement or HTTP read-after-write
+ verification. For binary uploads, download to a temporary file and compare
+ hashes or bytes when correctness matters.
+ 10. Do not start a pull/push daemon unless the user explicitly asks for ongoing
+ synchronization. The direct commands are designed to avoid that workflow.
+ 11. After repeated authentication failures, ask the user to refresh the cookie;
do not keep retrying a possibly expired credential.
- 11. For a sequence of edits to one project, reuse a persistent `olcli live`
- session instead of paying a fresh connection per change. On macOS or Linux,
- where `tmux` exists, host that session in tmux (one window per project) with
- `scripts/run-live.sh`, and drive it with `scripts/olcli-live send`, which
- waits for each reply. On Windows, skip this: the helpers are bash scripts
- and there is no PowerShell twin, so start a session per request instead.
- Keep one writer per window: two senders at once interleave their replies and
- you can no longer tell which reply belongs to which operation.
## Bundled implementation
The modified olcli source and compiled JavaScript live in `assets/olcli/`.
Install it with the platform script in `scripts/`; do not silently substitute
the public npm release because it may not contain this Skill's direct-edit
commands.
- macOS/Linux: `bash scripts/install_olcli.sh`
- Windows PowerShell: `powershell -ExecutionPolicy Bypass -File scripts/install_olcli.ps1`
- Verify macOS/Linux: `bash scripts/check_olcli.sh`
- Verify Windows: `powershell -ExecutionPolicy Bypass -File scripts/check_olcli.ps1`
When changing the bundled implementation, update both `assets/olcli/src/` and
`assets/olcli/dist/`, run the TypeScript build, and validate this Skill before
delivery.