Skip to main content
This guide walks through using DocWriter on an existing Overleaf project. The end state is a workflow where:
  • You edit .tex files locally in DocWriter.
  • The PDF rebuilds on every save and a preview window stays in sync.
  • Double-clicking the PDF jumps to the source line.
  • Accepted edits flow back to Overleaf as git commits after each agent turn.

​
Prerequisites

  • DocWriter installed.
  • A TeX distribution with pdflatex, bibtex, and synctex on your PATH. On macOS, MacTeX is the easiest install. On Linux, install texlive-full.
  • git on your PATH.
  • An Overleaf project. The free tier supports git integration; for older free accounts you may need the paid plan.

​
1. Get the project locally

Overleaf offers two ways to sync a project to your machine. Either works with DocWriter; pick whichever fits your existing workflow. If you use GitHub already, this is the cleaner path. In Overleaf, open the project’s Menu (top-left), find the Sync section, and click GitHub. Authorize Overleaf to access your GitHub account, then pick a repository (or let Overleaf create one). Overleaf will keep the two sides in sync going forward. Then on your machine:
You push and pull from GitHub like any other repo. Overleaf handles the round-trip back to its own editor.

​
Option B: Clone Overleaf’s git endpoint directly

Overleaf also exposes a direct git remote at git.overleaf.com. In the project’s Menu, Sync section, click Git to find the clone URL:
On the first clone, Overleaf prompts for a one-time git token. Generate it from your account settings and use it as the password when prompted.

​
2. Open the project in DocWriter

A browser opens. The file tree shows your project’s contents (typically main.tex or whatever your entry file is named, plus chapter files, a .bib, and figures). Click main.tex. It opens as a tab in the editor. .tex source is shown as plain text. DocWriter does not try to render LaTeX in the editor; the preview window does that.

​
3. Wire up the LaTeX build hook

In the menu bar, open Settings and click Hooks. In the template chip row, click the pdflatex chip. The add-form fills in:
  • Event: PostToolUse
  • Matcher: Edit|Write
  • Command:
  • Output: main.pdf
If your entry file is not named main.tex, edit the command (replace both main.tex and main) and the output (replace main.pdf) to match. The three pdflatex passes and the bibtex call resolve cross-references and citations in one go. The -synctex=1 flag is what makes double-clicking the PDF jump to source later. Click + to save.

​
4. First build

Click Run now on the new hook. The first run takes a few seconds and the history pane shows the progress. On success, the hook produces main.pdf in the project root. If the build fails, the history pane shows the stderr. Common first-run issues:
  • Missing packages. Install via tlmgr install <package> if you are on TeX Live, or run the build once outside DocWriter so MacTeX can auto-install.
  • Wrong entry file name. Edit the hook’s command and output.

​
5. Open the preview

A Preview button now appears in the top-right of the editor (because the active tab’s stem matches the hook’s output). Click it. A popup window opens with the PDF. Drag it to a second monitor or arrange it side-by-side with DocWriter.
A .tex file open in the editor with a [[ ... ]] directive asking for a TikZ figure
To see the loop in action, drop an inline directive into the source. For example, after \section{Introduction} add a single commented line:
The leading % keeps pdflatex happy if it builds before the agent handles the directive; the agent still picks the directive up. A few seconds after you stop typing, the agent reads the file, adds the necessary \usepackage{tikz} to the preamble, replaces the commented line with a real \begin{figure} block, and proposes both as pending reviews. You can keep editing the document while this is happening. The screenshot below was captured mid-flight: the agent’s proposed TikZ block sits as a pending review on the right, the directive is struck through in the editor, and a sentence typed by the user at line 114 (in the abstract body) is already in the document, plain prose, no conflict. The two streams are concurrent edits on the same file.
The agent's proposed TikZ figure landing as a pending review while the user concurrently types a note in the abstract
Accept the pending reviews in order (the right pane enforces oldest-first). The accepted edits flush to disk, the pdflatex hook fires on the next tool call (or click Run now on the hook to force it), and the preview window reloads with the rendered figure. The side-by-side view: editor on the left after acceptance, PDF on the right after rebuild.
Editor with the accepted TikZ figure code
PDF preview popup showing the newly added figure rendered

​
6. Test the loop

Edit something in main.tex. The hook fires on every save, pdflatex rebuilds, and the preview window reloads with the new PDF. Scroll position is preserved across reloads. Double-click any text in the PDF preview. DocWriter resolves the click to a source line via synctex, switches to that file in the editor, and scrolls to the line.

​
7. Add the auto-push hook

To send your work back to Overleaf as you go, add a git hook: In the hooks panel, click the Git auto-commit & push on Stop chip. The form fills in:
  • Event: Stop
  • Command:
Click + to save. The hook fires after every agent turn ends. It commits any pending changes (your typing and any accepted agent edits) and pushes to the current branch’s upstream.
If git push ever prompts for credentials, run it once manually in a terminal so your git credential helper caches the Overleaf token. DocWriter cannot answer a credential prompt.

​
8. Drive the agent

Click Send in the top-right of the editor. Type a prompt:
Tighten the abstract.
After three seconds, the agent submits. It calls read_doc on main.tex, then edit_doc with the proposed change. The change appears as a pending review in the right pane. Click Accept. The accepted edit:
  1. Counts as an Edit tool call, so your pdflatex hook fires.
  2. The preview window reloads with the rebuilt PDF.
  3. The turn ends, Stop fires, the git hook commits and pushes.
Your Overleaf project now has the agent’s revision, pushed from DocWriter without leaving the editor.

​
9. Pull collaborator changes

DocWriter does not auto-pull. If you have collaborators working in Overleaf’s web editor (or via GitHub if you chose Option A in step 1), periodically run:
You can wire this as a SessionStart hook if you want it to run every time DocWriter starts:
  • Event: SessionStart
  • Command: git pull --rebase --autostash || true
(--autostash and || true ensure the hook does not fail if you have uncommitted local changes.) With the GitHub sync path (Option A), pushes from DocWriter land in your GitHub repo; Overleaf picks them up on its next sync. Pulls happen in the other direction. The latency between Overleaf and GitHub is usually a few seconds.

​
Troubleshooting

Preview button doesn’t appear. The active tab’s stem does not match any hook’s output. Check that the hook has an output field set and that it matches your entry file (e.g. main.pdf, not paper.pdf). Double-click PDF does nothing. Make sure pdflatex ran with -synctex=1 (the template includes it) and that the synctex binary is on your PATH. Run which synctex to verify. Auto-push hook silently fails. Check the hook’s history-pane card for stderr. Most commonly: no upstream set on the branch, or the credential prompt is asking for a token DocWriter cannot answer. Push once from a terminal to seed credentials. Brackets in agent edits fail to apply. The markdown serializer escapes [ as \[. This rarely matters for .tex files but can come up. If an agent edit fails with “old_string not found”, look for an escaped bracket in the source.

​
Where to go next

  • Hooks. Write your own hooks for other toolchains.
  • Live preview. Synctex, themes, and HTML/image previews.
  • Delegating tasks. Longer-running agent work (multi-file rewrites, build-fix loops).