Skip to content

Working with Overleaf: a Git-based workflow ​

Overleaf's Git integration lets you clone an Overleaf project locally, run TeXRA's agents and latexdiff in VS Code or the terminal, and push commits back to Overleaf for your coauthors.

Works from the CLI too

The clone → edit → push loop below works in the terminal as well. After cloning, run agents with the texra CLI (e.g. texra run edit --input main.tex) instead of the VS Code panel, then commit and push as usual.

Prerequisites ​

  • Overleaf account with Git access enabled for your project (check Overleaf plans).
  • An Overleaf Git authentication token (starts with olp_). Generate one from Account Settings → Git Integration. Read Overleaf's token documentation for step-by-step instructions.
  • Git installed locally. Install it using your platform's package manager:
    • macOS: brew install git (via Homebrew), or run xcode-select --install to get git as part of the Xcode Command Line Tools.
    • Windows: Download the installer from git-scm.com, or install via winget install --id Git.Git -e.
    • Linux (Ubuntu/Debian): sudo apt-get install git.
  • TeXRA installed as either the VS Code extension or the texra CLI (installation guide).

Workflow steps ​

The whole loop is a round trip: pull your project down from Overleaf, edit it locally with TeXRA, then push your commits back.

Overleafcollaboration · browser
VS Code + TeXRAlocal AI editing
1Clonepull project down
2EditTeXRA agents
3Commitgranular history
4Syncpush back up

Clone or pull brings the project into VS Code, where TeXRA's agents do the editing; git push sends your committed changes back to Overleaf for your collaborators.

1. Clone your Overleaf project ​

  1. In VS Code, open the Command Palette (Ctrl/Cmd+Shift+P) and run TeXRA: Clone Overleaf/ShareLaTeX Project.
  2. Paste the Overleaf project URL or 24-character project ID when prompted.
  3. Enter your Overleaf Git token (it begins with olp_). TeXRA saves it to ~/.texra/secrets/ so future clones can reuse it.
  4. The command runs git clone directly into your workspace root, so the cloned project becomes the repository you're working in. Make sure that folder is empty before starting.
1
>TeXRA: Clone Overleaf/ShareLaTeX Project
TeXRA: Clone Overleaf/ShareLaTeX ProjectTeXRA
2
https://www.overleaf.com/project/64f8a2c1d3e5b6f7a9c0b1d2
Enter project URL or 24-character project ID.
3
olp_••••••••••••••••••••
Overleaf Git Token Saved to ~/.texra/secrets/

Three steps: pick the command, enter the project URL or 24-character ID, then enter your olp_ token, which is saved in ~/.texra/secrets/ for next time.

Token storage: Reset the saved token at any time by removing its entry from ~/.texra/secrets/. The token is never written into the clone's remote URL: after cloning, TeXRA offers it to your Git credential helper (the macOS keychain or Git Credential Manager, for example) so later pulls and pushes sign in. Without a helper, Git asks for it; enter the token as the password.

Option B: use the TeXRA CLI ​

Pass either the Overleaf project URL or its 24-character project ID, and optionally the directory to create or clone into (the working directory when left out):

bash
texra clone 0123456789abcdef01234567 ./project

The CLI requests the Git token without displaying it and saves the token in TeXRA's local secret store. Later clones reuse the saved token. In scripts, --no-input disables the prompt; the command then requires a token saved by an earlier interactive invocation. Self-hosted ShareLaTeX project and Git URLs are accepted by the same command.

Option C: manual terminal fallback ​

  1. Overleaf: Go to your project > Menu > Git. Copy the Git clone URL (https://git.overleaf.com/YOUR_PROJECT_ID). Overleaf Git Menu
  2. Local terminal: Go to the local directory you want and run:
    bash
    git clone https://git.overleaf.com/YOUR_PROJECT_ID your-local-folder
    When prompted for a password, enter your Overleaf Git token (olp_…). For the username, enter any non-empty value (e.g. git).

2. Edit locally with TeXRA in VS Code ​

Open your-local-folder in VS Code and run your agents and programs (research, latexDiff, edit, merge, etc.) as usual. Optionally use LaTeX Workshop for local PDF previews (LaTeX compilation setup).

Edit locally in VS Code
  • Select files, agent, modelPick what to edit and which model runs
  • Write instructionsDescribe the change in plain language
  • Start taskRun the agent on your selection
  • Review outputsInspect the r0/ revision in run storage
  • latexdiff / mergeDiff, compare or merge edits from the LaTeXDiffs sheet

Each toolbar action in the local edit loop, from selecting files and writing instructions through Start task, reviewing outputs, and latexdiff/merge.

3. Commit local changes ​

As you work, commit changes often using VS Code's Source Control () or the terminal:

bash
# Stage changes (e.g., all modified files)
git add .
# Commit with a descriptive message
git commit -m "Refine methodology section with TeXRA"

4. Sync back to Overleaf ​

  1. (Recommended) Pull: Fetch and merge any changes made directly on Overleaf since your last pull:
    bash
    git pull
    Resolve any merge conflicts locally using standard Git tools.
  2. Push: Upload your local commits to Overleaf:
    bash
    git push
    Refresh Overleaf in your browser to see the synced changes.

Important considerations ​

  • Merge conflicts: Pull changes from Overleaf before pushing your local work to keep conflicts small.
  • Authentication: Git may re-prompt for Overleaf credentials. If your token expires, generate a new one from Overleaf account settings (read the token documentation).
  • Large projects: Overleaf Git has size limits; keep them in mind for large projects.

Next steps ​