TeXFrog

TeXFrog helps cryptographers manage game-hopping proofs in LaTeX. If you have ever maintained a dozen nearly-identical game files by hand, copying lines between them and trying to keep highlights consistent, TeXFrog is meant to solve that problem.

Key idea: Write your pseudocode once in a single .tex file. Tag content with the games it belongs to using \tfonly{games}{content} commands. TeXFrog produces:

• Individual per-game renderings with changed lines automatically highlighted (via pdflatex — no extra tools needed)
• Consolidated comparison figures showing multiple games side by side (via pdflatex)
• An interactive HTML viewer for navigating the proof in a browser (via the optional Python CLI)

All from that one source file.

TeXFrog currently supports the cryptocode, nicodemus (by Bertram Poettering; not on CTAN, bundled with TeXFrog), and algpseudocodex pseudocode packages, and we are open to supporting others.

A snippet of the source file:

\tfonly{G0-G2}{k \getsr \{0,1\}^\lambda \\}
...
\tfonly{G0}{y \gets \mathrm{PRF}(k, r) \\}
\tfonly{G1}{y \getsr \{0,1\}^\lambda \\}
\tfonly{Red1}{y \gets \OPRF(r) \\}
...
\tfonly{G0,G1,Red1}{c \gets y \oplus m_b \\}
\tfonly{G2}{c \getsr \{0,1\}^\lambda \\}

Content outside \tfonly appears in every game. Content inside \tfonly{tags}{...} appears only in the listed games. Ranges like G0-G2 are resolved by position in the game list, so reductions interleaved between games work naturally.

When you want to include game figures in a certain spot in your paper:

\tfrendergame{myproof}{G1}
\tfrendergame[diff=G1]{myproof}{G2}

For proofs with many hops, a diffed render can end up mostly showing lines carried over unchanged from earlier games. Mark segment boundaries in the source with \tfsegment{Caption}, then opt in to cropping:

\tfcropdefault{on}                              % crop every diffed render by default
\tfrendergame[diff=G3, crop=off]{myproof}{G4}   % force a full listing for this one call

A cropped render keeps only the segments that changed relative to the diff target (plus the always-kept opening and closing segments), collapsing runs of unchanged segments into a single elision line produced by the redefinable \tfsegmentstub{captions} macro. \tfsegment markers must sit at block depth 0 (never inside an \If/\For/\While), and the crop= key is PDF-only --- the HTML viewer follows only \tfcropdefault. See Writing a proof for the full reference.

TeXFrog has two components. Most users only need the LaTeX package.

If you just want to write game-hopping proofs in LaTeX with automatic diff highlighting and consolidated figures, all you need is the texfrog.sty file. No Python, no command line tools, no virtual environments.

Local installation:

1. Download texfrog.sty from the repository.
2. Place it in the same directory as your .tex file (or anywhere TeX can find it).
3. Add \usepackage[package=cryptocode]{texfrog} to your preamble.
4. Compile with pdflatex as usual.

On Overleaf: Upload texfrog.sty to your project and use it like any other local package.

This gives you everything needed to render individual games (\tfrendergame), consolidated comparison figures (\tfrenderfigure), and automatic change highlighting — all at compile time. See the tutorial-cryptocode-quickstart example for a complete working document.

The Python CLI adds an interactive HTML proof viewer, validation, scaffolding, and live-reload. Install it if you want the texfrog command-line tool.

Requirements:

• Python >= 3.10
• LaTeX — TeX Live or MacTeX (for pdflatex and pdfcrop)
• Poppler or pdf2svg — for pdftocairo (brew install poppler on macOS), or pdf2svg as an alternative

LaTeX and Poppler are needed for the HTML viewer (texfrog html).

Installation:

pip install texfrog

Many Python installations don't let you install global packages, so you'll need to create a virtual environment:

cd my_working_directory      # wherever you want to install the venv
python3 -m venv .venv
source .venv/bin/activate    # on macOS/Linux; use .venv\Scripts\activate on Windows
pip install texfrog

When you open a new terminal session and want to run TeXFrog, you will need to reactivate the Python virtual environment:

cd my_working_directory      # wherever you installed the venv
source .venv/bin/activate    # on macOS/Linux; use .venv\Scripts\activate on Windows

After activating the virtual environment, you can cd to any directory on your computer and run the texfrog command.

The fastest way to get started without Python is to copy the tutorial-cryptocode-quickstart example and modify it. Download texfrog.sty, main.tex, and macros.tex, then compile with pdflatex. On Overleaf, upload all three files to a new project.

The fastest way to start a new proof is with texfrog init. This creates a minimal, runnable proof (proof.tex, macros.tex, commentary/*.tex, texfrog.sty, and a .gitignore) with comments explaining each field. The scaffold is self-contained — it bundles texfrog.sty (and nicodemus.sty for that profile), so pdflatex proof.tex works immediately with nothing else to download.

# Scaffold a new proof in the current directory using cryptocode for pseudocode
texfrog init

# ... or in a new directory
texfrog init mydirectory

# ... or using the nicodemus package for pseudocode
texfrog init myproof --package nicodemus

# ... or using the algpseudocodex package for pseudocode
texfrog init myproof --package algpseudocodex

The TeXFrog repository contains tutorials you can study:

# Download them from https://github.com/TeXFrog/TeXFrog/tree/main/examples
# or clone the repository using the following two lines:
git clone https://github.com/TeXFrog/TeXFrog
cd TeXFrog/examples

# Interactive HTML viewer with live reload
texfrog html serve tutorial-cryptocode/main.tex

texfrog init [DIRECTORY] [--package cryptocode|nicodemus|algpseudocodex]

Creates starter files in DIRECTORY (default: current directory). The --package option selects the pseudocode package (default: cryptocode). Existing files are never overwritten.

texfrog check proof.tex [--strict]

Parses the proof and runs validation checks (file existence, tag consistency, empty games, commentary references) without generating any output. Prints a summary and exits with code 0 if valid. With --strict, exits with code 1 if there are any warnings.

texfrog html build proof.tex [-o OUTPUT_DIR]

Compiles each game to SVG via pdflatex and produces a self-contained HTML site. Open index.html in any browser. Games are shown side by side with changed lines highlighted, and you can navigate with arrow keys.

texfrog html serve proof.tex [--port 8080] [--no-live-reload]

Builds the HTML site, starts a local server, and opens your browser. By default, TeXFrog watches your source files and automatically rebuilds and refreshes the web browser when you save changes. Use --no-live-reload to disable this.

You need a single .tex file that serves as both the LaTeX document and the TeXFrog source:

• proof.tex — declares the list of games and reductions, contains the pseudocode source with \tfonly tags, and optionally specifies commentary, figures, and which pseudocode package to use

See Writing a proof for a full guide, and the tutorials for worked examples.

All examples compile directly with pdflatex — no Python needed. Just place texfrog.sty in the same directory.

Comparing the cryptocode, nicodemus, and algpseudocodex tutorials shows the syntax differences between pseudocode packages.

• Writing a proof — reference for writing a TeXFrog proof
• Troubleshooting & FAQ — common problems proof authors may encounter

TeXFrog is in its early stages and we are actively looking for feedback from cryptographers who write game-hopping proofs. If you try TeXFrog on your own proof and run into rough edges, have ideas for features, or want to contribute code, please open an issue or pull request. Your input will help shape the tool into something genuinely useful for the community.

To set up a development environment:

pip install -e ".[dev]"

TeXFrog was originally created by Douglas Stebila, based on discussions with many people over the years about the desire for a tool for managing LaTeX source code of pen-and-paper proofs. Much of this codebase was vibe-coded with the assistance of large language models, especially Anthropic Claude.

TeXFrog is released under the Apache License 2.0. See LICENSE.txt for details.