Working with Overleaf: a Git-based workflow

Overleaf is a popular collaborative platform for writing LaTeX documents. By pairing Overleaf's Git integration with TeXRA, you gain local AI-assisted editing, specialized research agents, local tooling (such as latexdiff), and direct compilation in VS Code—while retaining real-time collaboration with coauthors on Overleaf.

This guide describes a workflow to clone your Overleaf project, run TeXRA locally in VS Code, and sync your changes back: Overleaf for collaboration, TeXRA for local editing and verification.

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 polish --input main.tex) instead of the VS Code panel, then commit and push as usual.

Why bridge Overleaf and TeXRA?

• Local AI editing: Apply TeXRA's specialized agents (correct, polish, research, paper2slide, etc.) directly on your local checkout.
• Precise local tooling: Use latexdiff for visual change tracking and local LaTeX engines for fast previews.
• Full editor ecosystem: Leverage VS Code's rich extension ecosystem, including LaTeX Workshop and custom keybindings.
• Granular version control: Work with standard Git branches, commit histories, and offline workflows.

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

git clone / pull git push

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

Option A: use TeXRA's clone command (recommended)

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 Project

TeXRA: Clone Overleaf ProjectTeXRA

2

https://www.overleaf.com/project/64f8a2c1d3e5b6f7a9c0b1d2

Paste Overleaf project URL or 24-character project ID

3

olp_••••••••••••••••••••

Overleaf Git token (olp_…) Saved to ~/.texra/secrets/

Three quick-input prompts: pick the command, paste 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

Create an empty destination directory, then pass either the Overleaf project URL or its 24-character project ID:

mkdir project
texra clone 0123456789abcdef01234567 --cwd ./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).
2. Local terminal: Go to the local directory you want and run:

   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

1. Open your-local-folder in VS Code.
2. Use TeXRA as usual:
   • Select files, agent, model.
   • Write instructions.
   • Execute ().
   • Review outputs (r0/<input filename>.tex, for example r0/main.tex; each revision keeps the input filename) from run storage.
   • Use latexdiff () or merge ().
   • Use features like auto-extract () and tool options ().
   • Optionally use LaTeX Workshop for local 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
• ExecuteRun the agent on your selection
• Review outputsInspect r0/output.tex from run storage
• latexdiff / mergeCompare or fold edits with code-compare & merge
• Auto-extract & toolsPull figures and toggle tool options

Each toolbar action in the local edit loop, from selecting files and writing instructions through Execute, reviewing outputs, latexdiff/merge, and auto-extract.

3. Commit local changes

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

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

4. Sync back to Overleaf

1. (Recommended) Pull: Fetch and merge any changes made directly on Overleaf since your last pull:

   git pull

   Resolve any merge conflicts locally using standard Git tools.
2. Push: Upload your local commits to Overleaf:

   git push

   Refresh Overleaf in your browser to see the synced changes.

Important considerations

• Merge conflicts: The most likely problem. 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.

This Git-based workflow lets you use TeXRA's local AI and tooling on your Overleaf projects while keeping Overleaf for collaboration.

Next steps

• Best practices: get more out of TeXRA.
• LaTeX Diff: change comparison in detail.
• Intelligent Merge: AI-assisted merging.