texspark’s AI panel talks to Claude, ChatGPT, or Gemini — with your own API key, on your own terms. Setup is one paste per provider. This guide covers getting a key, entering it, and what it actually costs (less than you’d guess).

1. Get an API key

An API key is a pay-as-you-go credential — different from a ChatGPT Plus or Claude Pro subscription. You create one in the provider’s console, and you’re billed only for what you use:

• Claude (Anthropic) — console.anthropic.com → API Keys → Create Key
• ChatGPT (OpenAI) — platform.openai.com/api-keys → Create new secret key
• Gemini (Google) — aistudio.google.com/apikey → Create API key

You only need one provider to start — pick whichever you already have an account with. The key is a long string starting with something like sk-; copy it right away, some consoles show it only once.

2. Enter it in texspark

Open Preferences → AI, and paste the key into the field for that provider. That’s it — the key is stored in the macOS Keychain automatically, never in a plain file, and it’s sent nowhere except to the provider you chose.

Each provider has its own field, so you can set up one, two, or all three and switch freely later.

3. Start a conversation

Hit ⌘T — the PDF panel flips to the chat. In the panel header, pick the provider and then a model from the dropdown (each provider lists its available models; the default is a sensible middle ground).

• Attach your document — one toggle sends your source as context, so the assistant answers about your file, not a pasted fragment.
• Send a selection — highlight a paragraph and press ⌘⇧A to ask about exactly that part.
• Paste the answer straight back into the editor, and ⌘B.

What does it cost?

Far less than people expect. API pricing is per-token (roughly, per word), and LaTeX questions are small: asking about an error, rewording a paragraph, or generating a table costs a fraction of a cent to a few cents, depending on the model and how much of your document you attach. Regular use while writing a thesis typically lands in the range of a coffee or two per month — and every provider’s console shows a live usage page, so nothing surprises you.

If you’re cost-conscious, pick a smaller model from the dropdown for everyday questions and switch to a bigger one when a derivation actually needs it.

Questions, or a provider behaving oddly? Email support@texspark.io — it goes straight to the developer.

texspark was built around one workflow: a project that’s split across many files — a main.tex, a folder of chapters, a .bib somewhere. This guide sets that up from zero. It takes about two minutes.

1. Open your root file

Open the file that holds your \documentclass — the one with the \include or \input lines. For most projects that’s main.tex or manuscript.tex.

That’s genuinely all you open. texspark has no “open folder” step and no project file to create — the root file is the project, because everything else can be discovered from it.

2. Make it the build target

Double-click its tab. (Or press ⌘⇧P.) A 🔨 appears on the tab — that file is now the build target.

This one gesture is the whole setup. From now on:

• The outline immediately reads the whole \include tree — every chapter in document order, including files you’ve never opened. No build needed.
• ⌘B builds the root, no matter which file you’re editing. Chapter twelve, the appendix, a figure caption — ⌘B always compiles the right thing.
• \ref{, \cite{, and SyncTeX all work project-wide: labels from other chapters autocomplete, every .bib the project references is found, and ⌘-clicking the PDF lands in the right sub-file.

3. Work from the outline

Click any section in the outline and the right file opens at the right line — that’s how you move between chapters. There’s no file browser in the sidebar, and after a day you won’t miss it: the outline is a better map of a book than a folder listing ever was.

Sub-files you open this way come up as ordinary tabs. Edit, ⌘B, and the root rebuilds; the PDF stays where you were.

The one rule: start from the root

Order matters once: open the root file first and set it as the target before you wander into chapters.

The reason is honest logic, not a limitation to apologize for: a chapter file doesn’t mention its parent. main.tex says \include{chapters/ch3}; ch3.tex says nothing about main.tex. So if you open a lone chapter first, texspark has no way to know which document it belongs to — no editor does. Start from the root, where the relationships are declared, and everything downstream follows.

(If you arrive in a sub-file through texspark — from the outline or a ⌘-click in the PDF — the parent is already known, and the build target is handled for you.)

A layout that works

texspark doesn’t impose a structure, but if you’re starting fresh, this is a comfortable one:

book/
├── main.tex          ← build target 🔨
├── references.bib
├── chapters/
│   ├── ch1.tex
│   ├── ch2.tex
│   └── ch3.tex
└── figures/

Sub-folders in \include{chapters/ch1} are fine — the outline and SyncTeX follow paths, not just filenames.

That’s the whole setup: open the root, double-click its tab, write. If anything here doesn’t match what you see, email support@texspark.io — it goes straight to the developer.

LaTeX rarely finishes in one pass. Cross-references need a second run. A bibliography needs BibTeX in between. An index needs makeindex. If you’ve been running these by hand in Terminal — or clicking through a sequence of menu items — this guide sets it up as a single ⌘B.

Why more than one pass

A quick refresher, because knowing why makes the command obvious:

On the first run, LaTeX doesn’t yet know what page Section 3 lands on, so \ref and \cite come out as ??. It writes what it learned into .aux. BibTeX (or makeindex) then reads those files and produces .bbl (or .ind). A second LaTeX run picks those up — and sometimes a third is needed, because inserting the bibliography shifts page numbers, which changes the references again.

Hence: run, process, run, run.

The command box

Open Preferences (⌘,) → Compile. You’ll find one-click templates for the usual engines — xelatex, pdflatex, lualatex, latexmk, BibTeX, makeindex — which is the fastest way to get a working build.

But the templates only fill in the command box; they don’t lock it. The field itself is fully editable, so you can start from a template and modify it, or ignore them entirely and type your own pipeline from scratch. Anything your shell can run, texspark can run. Steps chain with && — meaning each step runs only if the previous one succeeded, so a failure stops the chain instead of cascading nonsense.

Two tokens get substituted before the command reaches the shell:

• {file} → main.tex (build target with extension)
• {filename} → main (without extension)

Both are shell-escaped, so spaces in your path won’t break anything. The command runs in the build target’s directory.

Recipes

Bibliography (BibTeX):

xelatex -synctex=1 {file} && bibtex {filename} && xelatex -synctex=1 {file} && xelatex -synctex=1 {file}

Note that BibTeX takes {filename} — no extension — while LaTeX takes {file}. Getting this backwards is the single most common mistake here.

Index (makeindex):

xelatex -synctex=1 {file} && makeindex {filename} && xelatex -synctex=1 {file}

Both, for a book:

xelatex -synctex=1 {file} && bibtex {filename} && makeindex {filename} && xelatex -synctex=1 {file} && xelatex -synctex=1 {file}

Or let latexmk figure it out:

latexmk -xelatex -synctex=1 -interaction=nonstopmode {file}

latexmk decides how many passes are needed and runs BibTeX when appropriate. If your project is standard, this is the least fussy option — and texspark keeps your PDF scroll position through all of latexmk’s rewrites, so a five-pass rebuild doesn’t fling you back to page one.

Keep -synctex=1

Every LaTeX invocation in the chain should carry -synctex=1. That’s what produces the .synctex.gz file next to your PDF, which is what makes ⌘⇧↩ and ⌘-click work. Drop it from the final pass and forward/inverse search quietly stops working.

When a step fails

The chain stops at the first failure, and the bottom panel switches to Issues automatically. Click any error row to jump to the offending line — in the right sub-file, not just the build target.

Two things worth knowing:

• BibTeX errors don’t always surface as LaTeX errors. If your bibliography comes out empty, check the Log tab (next to Terminal and Issues) for BibTeX’s own complaints — a missing .bib entry usually shows up there.
• If a run leaves things in a strange state, ⌘⇧⌫ sweeps the build directory clean of .aux, .bbl, .ind, .toc, and friends, leaving your .tex and .pdf alone. Then build fresh.

One target, any chapter

Worth restating: mark your project root as the build target (⌘⇧P) and this chain runs against it no matter which chapter you’re editing. Multi-pass builds and multi-file projects were the two things that used to make me alt-tab to Terminal. Now they’re one keystroke.

If you’re coming from Texmaker — as I did, after ten years — almost everything you know transfers. This guide maps your Texmaker habits to their texspark equivalents, plus the handful of things that work differently (usually: automatically).

The mental model

One thing changes: texspark has no “master document” mode. Instead, you mark a tab as the build target (🔨), and it stays the build target across sessions until you clear it. Same idea, less ceremony — you set it once, not once per session.

Keyboard mapping

You did this in Texmaker	Do this in texspark
Quick Build (F1)	⌘B
Define Master Document	⌘⇧P (or double-click the tab)
View Log	Log tab in the bottom panel (⇧⌘Y toggles)
Structure panel	Outline in the left sidebar
PDF forward search	⌘⇧↩
PDF inverse search	⌘-click
Clean auxiliary files	⌘⇧⌫
Find / Replace	⌘F / ⌘R

Setting up your existing project

1. Open your project’s main file — drag it (or the whole folder’s files) onto texspark, or ⌘O
2. Mark it as the build target: ⌘⇧P or double-click its tab. A 🔨 appears
3. Pick your build command: Preferences (⌘,) → Compile. If you used Texmaker’s Quick Build with xelatex, choose the xelatex template — or chain steps with && (e.g. xelatex {file} && makeindex {filename} && xelatex {file})
4. Build: ⌘B from anywhere — any chapter, any sub-file. It always compiles the build target

That’s the whole migration. Your .tex files don’t change at all.

What works differently (better, mostly)

• The outline covers the whole project. Texmaker’s Structure panel shows each open file separately; texspark’s outline follows every \input/\include from the build target as one tree — including files you haven’t opened
• Sub-files find their parent. ⌘-click in the PDF into a chapter file, and that chapter’s parent automatically becomes the build target. No re-declaring
• Sessions restore completely — tabs, cursor positions, the build target, panel layout. Quit and relaunch mid-thesis without ceremony
• No built-in \paragraph limit. The outline goes all the way down (I patched Texmaker’s source once to get \paragraph support; here it just works)

What Texmaker has that texspark doesn’t

Honesty section: Texmaker is free, runs on Windows and Linux, and has years of maturity. If you work across platforms, keep it — your files are identical either way, so you can even use both.

Try it with your real project

The 14-day trial is the full app — open your actual thesis or book, set the build target, and see if ⌘B from chapter 4 feels as good as I think it does. texspark.io/download