> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docwriter.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Editing an Overleaf LaTeX project

> Open an Overleaf LaTeX project in DocWriter, build the PDF on every edit, and push changes back to Overleaf over git.

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](/install).
* A TeX distribution with `pdflatex`, `bibtex`, and `synctex` on your
  `PATH`. On macOS, [MacTeX](https://www.tug.org/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.

### Option A: Sync to GitHub (recommended)

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:

```sh theme={null}
git clone git@github.com:<you>/<repo>.git ~/writing/my-paper
cd ~/writing/my-paper
```

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:

```
https://git.overleaf.com/abc123def456
```

```sh theme={null}
git clone https://git.overleaf.com/abc123def456 ~/writing/my-paper
cd ~/writing/my-paper
```

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

```sh theme={null}
docwriter --new-session ~/writing/my-paper
```

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:
  ```sh theme={null}
  pdflatex -interaction=nonstopmode -halt-on-error -synctex=1 main.tex \
    && (bibtex main || true) \
    && pdflatex -interaction=nonstopmode -halt-on-error -synctex=1 main.tex \
    && pdflatex -interaction=nonstopmode -halt-on-error -synctex=1 main.tex
  ```
* 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.

<Frame>
  <img src="https://mintcdn.com/ucberkeley-8d9be701/pOA9wX63uxLFsbqp/images/overleaf-tex-open.png?fit=max&auto=format&n=pOA9wX63uxLFsbqp&q=85&s=6bd33ce9ec179821aa7bbaccf03056f3" alt="A .tex file open in the editor with a [[ ... ]] directive asking for a TikZ figure" width="1400" height="900" data-path="images/overleaf-tex-open.png" />
</Frame>

To see the loop in action, drop an inline directive into the source.
For example, after `\section{Introduction}` add a single commented
line:

```tex theme={null}
% [[ Add a small TikZ figure showing writer-agent-document collaboration: three labeled nodes with bidirectional arrows. Load tikz in the preamble if needed. Wrap in a figure environment with a caption. ]]
```

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.

<Frame>
  <img src="https://mintcdn.com/ucberkeley-8d9be701/pOA9wX63uxLFsbqp/images/overleaf-pending-edit.png?fit=max&auto=format&n=pOA9wX63uxLFsbqp&q=85&s=dd3f77f802de64c39412a6fa6f43a1c0" alt="The agent's proposed TikZ figure landing as a pending review while the user concurrently types a note in the abstract" width="1400" height="900" data-path="images/overleaf-pending-edit.png" />
</Frame>

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.

<div style={{display: 'grid', gridTemplateColumns: '2fr 1fr', gap: '0.75rem', marginTop: '1rem', marginBottom: '1rem'}}>
  <Frame>
    <img src="https://mintcdn.com/ucberkeley-8d9be701/pOA9wX63uxLFsbqp/images/overleaf-tex-open.png?fit=max&auto=format&n=pOA9wX63uxLFsbqp&q=85&s=6bd33ce9ec179821aa7bbaccf03056f3" alt="Editor with the accepted TikZ figure code" width="1400" height="900" data-path="images/overleaf-tex-open.png" />
  </Frame>

  <Frame>
    <img src="https://mintcdn.com/ucberkeley-8d9be701/pOA9wX63uxLFsbqp/images/overleaf-pdf-preview.png?fit=max&auto=format&n=pOA9wX63uxLFsbqp&q=85&s=8a0e9f696a42a4d852f784f5ae98f6d2" alt="PDF preview popup showing the newly added figure rendered" width="900" height="1100" data-path="images/overleaf-pdf-preview.png" />
  </Frame>
</div>

## 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:
  ```sh theme={null}
  git add -A && (git diff --cached --quiet || (git commit -m "docwriter: auto-commit" && git push))
  ```

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.

<Note>
  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.
</Note>

## 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:

```sh theme={null}
git pull
```

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](/automation/hooks). Write your own hooks for other toolchains.
* [Live preview](/automation/preview). Synctex, themes, and HTML/image
  previews.
* [Delegating tasks](/agent/delegating-tasks). Longer-running agent work
  (multi-file rewrites, build-fix loops).