TeXRA

Appearance

Working with TikZ Figures ​

TikZ is a powerful LaTeX package for creating vector graphics programmatically. It's widely used in academia for diagrams, plots, and technical illustrations because of its high quality and seamless LaTeX integration. Mastering TikZ can feel like learning a new language — TeXRA is here to help.

TeXRA offers specialised features for TikZ, built around its tool-use agents — which write TikZ, compile it, and visually verify the result — together with dedicated extraction / compilation tools. This guide focuses on TikZ-specific workflows.

No dedicated draw agent

Earlier versions of TeXRA shipped a standalone draw agent. Figure generation is now handled by the general tool-use agents (research or presenter), which can write TikZ, compile it, inspect the rendered output, and iterate until it looks right.

General Media Handling

For managing other figure types (standard images, PDFs) and general media selection in the UI, see the Working with Figures guide.

What is TikZ? (A Brief Intro) ​

Instead of using a graphical editor, TikZ lets you describe graphics with commands inside your LaTeX document. For example:

latex
\documentclass[tikz, border=2mm]{standalone}
\usepackage{tikz}
\begin{document}
\begin{tikzpicture}
  \draw[blue, thick] (0,0) circle (1cm);
  \node at (0,0) {Hello!};
\end{tikzpicture}
\end{document}

This code draws a blue circle with text inside. TeXRA's tools help manage and generate this kind of code.

Generating TikZ with Agents ​

A tool-use agent (research or presenter) acts as your AI graphics assistant for TikZ. It can:

  1. Create new TikZ figures from a textual description.
  2. Enhance existing figures with improvements or additions.
  3. Fix errors in TikZ code.
  4. Add annotations or labels to diagrams.

Because these are tool-use agents, they can compile the figure and inspect the rendered PDF, then refine the code until it compiles cleanly and looks correct.

researchdrawing a TikZ figure · iterating · this run
  • write_filefigures/ml-pipeline.texWrites a first draft of the flowchart
  • bashlatexmk ml-pipeline.texpdflatex OK → renders the standalone PDF
  • read_fileml-pipeline.pdfSees nodes overlap, one arrow misaligned
  • edit_filefigures/ml-pipeline.texAdjusts node spacing and arrow anchors, then recompiles

The agent writes, compiles, looks at the rendered PDF, and loops back to fix what it sees — a self-correcting draw cycle, not a one-shot generation.

TikZ Figure Example

Creating New Figures ​

  1. Select a tool-use agent — research or presenter ().
  2. Pick a vision-capable model () — sonnet46T, opus48T, gpt55, or gemini31p are good choices for complex drawings.
  3. Provide a detailed description of the figure you want.
  4. Click Execute ().

From the CLI, the same draw → compile → inspect loop shown below runs headlessly (texra run is for workflow agents only; tool-use agents like research use texra agents run):

bash
texra agents run research --input figures.tex \
  --instruction "Create a TikZ flowchart of the ML pipeline in Section 2."

Example instruction:

Create a TikZ figure showing a flowchart of the machine learning pipeline
described in Section 2. Include the following steps: data collection,
preprocessing, feature extraction, model training, and evaluation.
Connect the steps with arrows and add appropriate labels.

Enhancing Existing Figures ​

  1. Select the input file () containing the TikZ code.
  2. Select a tool-use agent (research or presenter).
  3. Provide instructions for the desired improvements.
  4. Execute ().

Example instruction:

Enhance the existing TikZ figure to add color coding for different components.
Use blue for input components, green for processing steps, and red for output.
Add a legend explaining the color scheme and improve the layout for better readability.

TikZ Extraction ​

TeXRA can pull TikZ figures out of your LaTeX source for separate processing.

Automatic Extraction ​

  1. Open the Auto Extract dropdown () next to the Media selector.
  2. Enable TikZ Figures.
  3. Select your input file(s) ().
  4. Execute your chosen agent ().
Media · Auto-extract
Auto Extract
Figures
TikZ Figures
Compile Input PDF

Open the wand Auto-extract menu in the Media group and check TikZ Figures — every tikzpicture in your selected files is then pulled out on the next run.

When automatic extraction is enabled, TeXRA will:

  1. Scan your LaTeX documents for tikzpicture environments.
  2. Extract each figure as a separate file.
  3. Compile the figures to generate PNG previews.
  4. Make both the TikZ code and previews available to the agent.

Manual Extraction Commands ​

You can also extract TikZ figures from the Command Palette:

  1. Open a LaTeX file containing TikZ figures.
  2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
  3. Run TeXRA: Extract TikZ Figures from Current File.

This creates standalone files for each TikZ figure in your document.

Agent Tool Calls ​

Tool-use agents can invoke extract_tikz_figures to perform the same discovery and optional compilation steps programmatically:

json
{
  "name": "extract_tikz_figures",
  "arguments": {
    "texPath": "figures/diagrams.tex",
    "compile": true
  }
}

With compile: true the tool emits standalone PDFs (one per figure) and attaches them so multimodal models can read the binary output directly. Set compile: false if you only need a summary of labels or plan to edit the extracted TikZ code yourself.

TikZ Compilation ​

Once extracted, TikZ figures can be compiled into viewable images.

Automatic Compilation ​

With automatic extraction on, one source file fans out into one standalone document, one PDF, and one PNG preview per figure — handed back to the agent:

Source

One .tex file with several tikzpicture environments.

diagrams.tex
Extract

A standalone LaTeX document per figure.

fig1.texfig2.texfig3.tex
Compile

latexmk / pdflatex builds each standalone.

3 PDFs
Preview

PDF → PNG via GraphicsMagick / ImageMagick + Ghostscript.

3 PNGs
Agent

Sees both the TikZ code and the rendered previews.

code + image

The extract → compile → preview pipeline: each tikzpicture becomes its own standalone document, PDF, and PNG. The last hop needs GraphicsMagick / ImageMagick + Ghostscript.

Missing system dependencies show on Dashboard → LaTeX ().

Manual Compilation ​

  1. Open the Command Palette (Ctrl+Shift+P).
  2. Run TeXRA: Compile TikZ Figures from Current File.

This compiles all extracted figures and generates preview images.

Customising TikZ Processing ​

Several settings tune how TeXRA handles TikZ. Access them from the Dashboard → LaTeX tab (), or set the keys below in .texra/config.json (CLI) or VS Code settings for power users.

TikZ Template ​

The standalone document structure TeXRA uses for each extracted figure:

json
"texra.latex.tikzTemplate": "\\documentclass[tikz,border=10pt]{standalone}\n\\usepackage{tikz}\n\\usepackage{pgfplots}\n\\usetikzlibrary{positioning}\n\\usetikzlibrary{patterns}\n\\usetikzlibrary{arrows.meta, shapes.geometric, matrix, calc, decorations.pathreplacing}\n\\usetikzlibrary{shapes, arrows}\n\n\\begin{document}\n{{ tikzpicture }}\n\\end{document}"

Customise this template to include additional packages or settings your figures need.

TikZ Input Directory ​

If your TikZ figures depend on custom styles or macros, specify an input directory:

json
"texra.latex.tikzInputDirectory": "/path/to/tikz/inputs"

The directory is added to the LaTeX search path when compiling figures.

Including Workspace in TEXINPUTS ​

By default TeXRA adds your workspace root to TEXINPUTS:

json
"texra.latex.includeWorkspaceInTexinputs": true

This helps LaTeX locate packages and styles stored elsewhere in the project.

Figure Libraries ​

Tool-use agents can reuse existing figures as references when creating new ones.

Using Reference Figures ​

  1. Add previous TikZ figures to the Reference section ().
  2. Mention them explicitly in your instructions.
  3. Ask the agent to adopt similar styles or approaches.

Example instruction:

Create a TikZ diagram of a neural network architecture similar to the one in
the reference file, but add an attention mechanism between the encoder and decoder.
Maintain the same visual style and color scheme as the reference figure.

Troubleshooting TikZ Issues ​

When a figure won't build, jump to the matching failure mode and work through its checks.

Compilation errorsfix
Check the LaTeX log for the error (build directory)
Verify required TikZ libraries are in the template
Ensure your distribution has the needed packages
Simplify figures that may exceed compiler limits
Missing packagesfix
Install packages via your LaTeX distribution manager
Add the packages to your TikZ template
Ensure package paths are in TEXINPUTS
Figure size issuesfix
Adjust the border in the standalone document class
Scale the figure with TikZ’s scale option
Resize specific elements, not the whole figure

Three failure modes, each with its quick remedies — find your symptom, fix it, recompile.

Best Practices ​

Effective TikZ Instructions ​

For best results when asking an agent to draw figures:

  1. Be specific — describe all elements and their relationships.
  2. Provide context — include purpose and intended audience.
  3. Specify style — mention colours, line styles, text formatting.
  4. Reference examples — point to similar figures when possible.

Figure Organisation ​

  1. Use consistent naming conventions for figures.
  2. Store extracted figures in a dedicated directory.
  3. Include comments in TikZ code explaining complex parts.
  4. Maintain a library of reusable figure components.

Performance Considerations ​

TikZ compilation can be resource-intensive:

  1. Split very complex figures into multiple smaller ones.
  2. Use the external library for caching compiled figures.
  3. Keep simplified versions for drafts; full detail for finals.

Next Steps ​