TeXRA

Appearance

File Management ​

Academic projects often involve juggling numerous files – main documents, chapters, figures, references, auxiliary styles... TeXRA aims to make this less of a circus act with its comprehensive file management system. This guide explains how to effectively organize, select, and manage files when working with TeXRA.

File Categories ​

TeXRA organizes files into three categories, each with its own accepted file types and read/write role:

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.

Input Files ​

These are the primary files the agent reads and edits. They typically include:

  • LaTeX documents (.tex)
  • Text files (.txt)
  • Markdown files (.md)

Input files can be a single main document or multiple related files (like chapters of a book or sections of a paper).

Context Files ​

Read-only files the agent sees but won't modify. They can be:

  • Bibliographies (.bib/.bbl)
  • Style and macro files (.sty/.cls)
  • Reference papers or previous versions
  • Any document the output should match for formatting

Figure & Media Files ​

Files containing visual or audio content, such as images, PDFs used as figures, or audio recordings. See the Working with Figures guide for details on supported types, UI controls, and automatic extraction.

Pasting Images from Clipboard ​

TeXRA supports directly pasting images from your clipboard into the instruction text area. This is useful for quickly including screenshots, diagrams, or other visual content:

  1. Copy an image to your clipboard (e.g., take a screenshot or copy from another application)
  2. Click in the instruction text area where you want to reference the image
  3. Paste (Ctrl/Cmd+V) - the image will be automatically:
    • Saved to the workspace storage
    • Referenced in the text as [pasted_timestamp_hash.ext]
    • Added to the Media Files list
    • Made available to the AI model

Pasted images appear in the file selector like any other media file, so you can review or remove them before sending. If the selected model cannot read images, TeXRA warns you so you can switch to a vision-capable model.

The clipboard paste feature accepts many image formats (JPEG, PNG, GIF, WebP, BMP, SVG, TIFF, HEIC, HEIF, AVIF, PSD), but the actual formats that can be processed depend on what the selected AI model supports. Most vision models support common formats like JPEG, PNG, GIF, and WebP.

Note: Pasted images are stored in workspace storage and automatically cleaned up after 3 days to save space.

File Selection Interface ​

The TeXRA interface provides a streamlined way to select and manage files using distinct sections 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 just a list of length one). The header exposes 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 just 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, just keep the list at length one.

This works well for:

  • Processing multiple chapters of a book
  • Working with documents split across multiple files
  • Batch processing similar documents
  • Including multiple reference materials

Output Files ​

For workflow agents 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 settings.defaultOutputFiles.

File Path Handling ​

TeXRA intelligently handles file paths to ensure proper document processing:

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: Workflow outputs are saved in task storage. Use Accept or Pack when you want to copy reviewed outputs back into the workspace.

File Path Configuration ​

You can customize file extensions and ignored paths via the texra.files.* settings — set them in .texra/config.json (CLI) or VS Code settings. The default values are listed in the Configuration Guide. A minimal example configuration might look like this:

json
"texra.files.included.inputExtensions": [".tex", ".md"],
"texra.files.ignored.directories": ["build", "node_modules"]

Output File Naming ​

TeXRA stores workflow outputs in the run's task storage folder. Within that folder, round outputs use a simple path:

r{round}/output.extension

For example:

  • Input: paper.tex
  • Agent: polish
  • Model: sonnet46
  • Output: r0/output.tex

When the agent definition includes reflection rounds, you may also see:

  • Round 1: r1/output.tex

File Management Commands ​

TeXRA provides several commands for managing generated files, accessible from the main interface or the ProgressBoard:

Pack ​

The "Pack" button () snapshots the run's task storage folder into a structured history folder:

  1. Creates a timestamped directory in the "History" folder
  2. Copies all relevant output files, logs, and mirrored dependencies
  3. Preserves the relationship between input and output files

This is useful for maintaining a clean workspace while preserving previous outputs.

Clean ​

The "Clean" button () removes output files for the selected run:

  1. Identifies the task storage folder for the current run
  2. Safely removes generated artifacts from task storage
  3. Leaves original input files untouched

Use this to remove generated artifacts from task-run storage after reviewing the results.

Opening Generated Files ​

Workflow outputs are listed in the ProgressBoard under Generated Files. Click a file name to preview it in VS Code. Files open using VS Code's default viewer, so PDFs and images display correctly while .tex documents open in the editor.

To browse the whole run folder, use the

Open in task storage toolbar

button. This reveals the task-run storage folder with generated files, compile logs, mirrored LaTeX dependencies, and intermediate artifacts. (From a terminal, texra history show <id> lists the same stored artifacts — see the card below.)

Task Run Storage ​

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

text
executions/<executionId>/

Workflow outputs are written there first, not directly over your workspace files. Three commands then move that run's artifacts to three different places:

Task-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 — its run store lives at .texra/runs/<run-id>/, and --output plays the role of Accept:

texra run
$texra run polish --input paper.tex
.texra/runs/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.saveDebugObjects is enabled.

Working with LaTeX Projects ​

For complex 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

Input File Detection ​

TeXRA automatically detects appropriate input files based on:

  1. File extension (.tex, .txt, .md)
  2. Location in project hierarchy
  3. Content structure

LaTeX Workshop Integration ​

If you use the popular LaTeX Workshop extension, TeXRA attempts to automatically configure some settings upon its first activation to ensure smoother integration and cleaner project structures. If the extension isn't installed, TeXRA will offer to install it for a smoother experience. These defaults are applied only if the corresponding settings are not already defined:

  • Output Directory: Sets latex-workshop.latex.outDir to %DIR%/build/. This directs LaTeX compilation output (like .aux, .log, .pdf files) into a build subdirectory within your project, keeping your main directory tidy.

    json
    "latex-workshop.latex.outDir": "%DIR%/build/"

  • Compilation Arguments: Adds arguments like -interaction=nonstopmode, -pdf, and -f to latex-workshop.latex.magic.args. These help LaTeX compile more robustly, especially when run by TeXRA agents.

  • Word Wrap: Enables word wrap specifically for .tex files ([latex].editor.wordWrap) for better readability of long lines.

These automatic configurations aim to provide a good default setup. They apply to the VS Code extension only (LaTeX Workshop is itself a VS Code extension); you can review and adjust them in your VS Code settings.json if needed.

Cross-Computer Syncing ​

For users working on multiple computers, we recommend using a cloud storage service like Dropbox to sync the following folders:

  • Log: Contains thinking logs and other processing information
  • Diffs: Stores difference files generated by LaTeX diff functionality
  • History: Keeps track of different versions of your documents

To maintain your local directory structure while syncing these folders, we suggest using soft links (symbolic links). This approach allows you to store the actual folders in Dropbox while creating symbolic links in your local project directory. For example:

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

Replace /path/to/Dropbox and /path/to/local with your actual Dropbox and local project paths.

Best Practices ​

Organizing Input Files ​

  • Main Document First: When using multiple input files, list the main document first
  • Logical Order: Arrange chapter files in logical reading order
  • Consistency: Maintain consistent file naming conventions

Managing Output Files ​

  • Regular Cleanup: Use the "Clean" command to remove unnecessary outputs
  • Version Control: Use "Pack" to preserve important milestones
  • Diff Review: Use LaTeXdiff to review changes before accepting them

Reference Materials ​

  • Relevant Examples: Include only directly relevant reference files
  • Context Limits: Be mindful of model context limits when adding references
  • Format Consistency: Use reference materials with similar formatting styles

Next Steps ​

Now that you understand how to manage files in TeXRA, you might want to learn about: