TeXRA

Appearance

File management ​

This guide explains how TeXRA organizes input files, read-only context, media attachments, and run-storage outputs.

File categories ​

TeXRA groups files into three categories:

InputRead + edit

Primary documents the agent reads and rewrites.

.tex.txt.md
ContextRead-only

Reference material the agent sees but never modifies.

.bib.bbl.sty.clsreference papers
MediaVisual / audio

Figures and recordings handed to vision/audio models.

imagesPDF figuresaudio

Three categories: Input is read + edited, Context is read-only, Media carries visual and audio content.

Read the Working with figures guide for supported media formats and automatic figure extraction.

Pasting images from the clipboard ​

Paste an image (Ctrl/Cmd+V) into the instruction box to save it to workspace storage as [pasted_<timestamp>_<rand>.ext] and add it to the Media list automatically. If the selected model does not support vision, TeXRA warns you before running. Pasted images are cleaned up after 3 days.

File selection interface ​

The TeXRA interface has a section for each file category (Input , Context , Media ):

draft.tex — texra-paper
\documentclass{article}
\usepackage{preamble} % from Context
\begin{document}
\input{sections/intro}
\includegraphics{figure1.pdf} % from Media
\bibliography{references} % from Context
\end{document}

Each category holds an ordered list of files with three quick actions in the header.

File list controls ​

Each category (Input, Context, and Media) manages a list of files; a single-file workflow is a list of length one. The header has three buttons:

  • Add opened files (): Append every editor tab whose extension matches the category to the list.
  • Clear all files (): Empty the list.
  • Add files (): Open a file picker to append files.

You can also drag and drop files from the OS file manager (or from VS Code's Explorer) onto a category to add them.

Inside the list:

  • Each file row has a small trash icon to remove that file.
  • Drag a row to reorder files. Input files are sent to the agent in this order.

The list is the only mode; there is no separate "single file" view. To work with one file, keep the list at length one.

Output files ​

For document tasks that edit documents, output filenames are the selected input filenames in the same order. Agents that create fixed new files declare those names in their YAML with task.outputs.

File path handling ​

TeXRA handles file paths as follows:

Relative vs. absolute paths ​

  • Display: Files are displayed with paths relative to the workspace root
  • Processing: TeXRA resolves paths to their absolute form when needed
  • Output: Document task outputs are saved in run storage. Use Accept or Pack when you want to copy reviewed outputs back into the workspace.

File discovery rules ​

TeXRA uses built-in file extensions and exclusions when discovering inputs, context, edited files, and media. Read the file discovery section of the configuration guide.

Output file naming ​

TeXRA stores document task outputs in the run folder under run storage. Within that folder, the revised document keeps your input filename in every revision (the first revision in r0/, the second in r1/, and so on):

r{round}/<input-filename>

Subdirectories are preserved, so chapters/intro.tex lands at r0/chapters/intro.tex. The only fixed name is the raw model response, r{round}/output.xml.

Run storage and file commands ​

Every run gets an isolated run folder under TeXRA's workspace storage directory:

text
executions/<executionId>/

Document task outputs are listed in the ProgressBoard under Generated Files (select a filename to preview it in VS Code, or use Open task folder to inspect generated files, compile logs, and mirrored dependencies). Three actions manage a run's artifacts:

  • Accept: Copies the reviewed output file into your workspace.
  • Pack / Archive outputs (): Copies the run's output files, logs, and mirrored dependencies into a timestamped folder under History/.
  • Clean / Delete output files (): Removes the generated artifacts from the run folder while leaving your workspace input files untouched.
Run storageisolated
executions/<id>/
r0/output.tex
r0/output.log
r1/output.tex
written here first — never over your workspace
Accept Workspacecopies reviewed outputs back in
Pack History/archives the whole run, timestamped
Clean Deletedremoves the run folder; inputs untouched

Accept copies reviewed outputs into the workspace, Pack archives the run into History, and Clean deletes the run folder. Your input files are never touched.

The CLI follows the same storage-first lifecycle: it reads and writes the same executions/<executionId>/ run store, and --output plays the role of Accept:

texra run
$texra run polish --input paper.tex
…/executions/9f3a6c81d24e/r1/paper.tex
outputs land in the run's storage folder first
$texra run polish --input paper.tex --output paper.polished.tex
paper.polished.tex
--output copies the final artifact next to your input
$texra history show 9f3a6c81d24e
… Execution / Status / Agent / Model details …
Files (2):
4128r0/paper.tex
4310r1/paper.tex

Three beats of the same lifecycle: storage-first output, --output as Accept, and history show to browse a run's stored files.

The folder also stores intermediate artifacts such as optional debug JSON files written when texra.debug.saveModelIO is enabled.

Working with LaTeX projects ​

For LaTeX projects with many files and dependencies:

LaTeX directory structure ​

TeXRA works well with standard LaTeX project structures:

project/
├── main.tex            # Main document
├── chapters/           # Chapter files
│   ├── intro.tex       # Introduction
│   └── methodology.tex # Methodology
├── figures/            # Figure directory
│   ├── diagram.pdf     # Figure file
│   └── graph.png       # Another figure
└── bibliography.bib    # Bibliography

LaTeX Workshop integration ​

If a LaTeX workspace does not have the LaTeX Workshop extension installed, TeXRA offers to install it. TeXRA does not rewrite editor or LaTeX Workshop preferences during startup. Use TeXRA's LaTeX settings page to inspect and apply the available workspace recommendations explicitly.

Cross-computer syncing ​

If you work on several computers, you can sync the History folder (which holds packed document versions) via a cloud storage folder using a symlink:

bash
ln -s /path/to/Dropbox/texra-projects/ProjectName/History /path/to/local/ProjectName/History

Next steps ​