Working with TikZ figures

TikZ is a LaTeX package for creating vector graphics programmatically. It is widely used in academia for diagrams, plots, and technical illustrations because of its output quality and its integration with LaTeX. Learning TikZ can feel like learning a new language. TeXRA helps with that, so the figures that illustrate a derivation or a result take less of your time than the theory itself.

TeXRA offers features built for TikZ, centered on its tool-use agents, which write TikZ, compile it, and visually verify the result, together with dedicated extraction and compilation tools. This guide covers the 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 other figure types (standard images, PDFs) and media selection in the UI, read 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:

\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 you manage and generate this kind of code.

Generating TikZ with agents

A tool-use agent (research or presenter) acts as your 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.

Creating new figures

1. Select a tool-use agent, research or presenter ().
2. Pick a vision-capable model (). sonnet5T, opus5T, gpt56, and gemini31p are good choices for complex drawings.
3. Describe the figure you want in detail.
4. Select Run agent ().

From the CLI, the same draw, compile, and inspect loop shown below runs headlessly (texra run takes workflow and tool-use agents alike, so a tool-use agent like research runs through it too):

texra 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. Describe the improvements you want.
4. Select Run agent ().

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 into standalone PDFs.
4. Make both the TikZ code and compiled PDFs 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:

{
  "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 and one compiled PDF 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

Attach

Models with native PDF support read the PDFs directly; others get rasterised PNGs via GraphicsMagick / ImageMagick + Ghostscript.

PDF or PNG

Agent

Sees both the TikZ code and the rendered output.

code + image

The extract, compile, attach pipeline: each tikzpicture becomes its own standalone document and PDF. Rasterization to PNG, only for models without native PDF support, 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 into standalone PDFs.

Customizing TikZ processing

Several settings tune how TeXRA handles TikZ. They have no control on the Dashboard, so set the keys below as flat texra.* keys in <project>/.texra/config.json (project) or ~/.texra/global-storage/config.json (user-wide). All three hosts read those files; TeXRA does not read VS Code settings.

TikZ template

The standalone document structure TeXRA uses for each extracted figure:

"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}"

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

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

"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 Context 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 does not build, find 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 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 colors, line styles, text formatting.
4. Reference examples: point to similar figures when possible.

Figure organization

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

• LaTeX Diff: compare document versions including figures
• LaTeX Tools: the full set of LaTeX tools TeXRA plugs into
• Best practices: general tips for working with TeXRA