termula

Install | Quick Start | AI Tools | Terminal Support | Repository | Contributing

termula detects LaTeX math in any text stream and renders it — as Unicode art in any terminal, or as crisp images in Kitty/WezTerm/iTerm2.

Rendering Modes

Image Mode	Unicode Art Mode
Kitty / WezTerm / Ghostty / iTerm2 Pixel-perfect math rendering via typst + mitex. Auto-detected by terminal capability. Kitty Graphics Protocol iTerm2 Inline Images	Any terminal High-quality text-based rendering via utftex. Works everywhere, no image support needed. Unicode Art ANSI Passthrough

Install

cargo install termula

Dependencies:

• utftex — Unicode art rendering (brew install utftex)
• typst — Image rendering, optional (cargo install typst-cli)

Homebrew (macOS)

brew tap nicokeywords/tap
brew install termula

Shell completions

# Bash
termula --completions bash > ~/.local/share/bash-completion/completions/termula

# Zsh
termula --completions zsh > ~/.zfunc/_termula

# Fish
termula --completions fish > ~/.config/fish/completions/termula.fish

Quick Start

# Pipe mode — filter any text stream
echo '$$\int_0^1 x^2 dx = \frac{1}{3}$$' | termula

# Wrapper mode — spawn a command in a pty, intercept its output
termula -- your-command

Use with AI Tools

This is termula’s primary use case — making math readable in LLM CLI output.

# Claude Code — wrap mode (preserves interactivity)
termula -- claude

# Pipe mode
claude | termula
aider | termula

Add this to your project’s CLAUDE.md for best results:

## Math Output

Output math using ```math blocks:

\```math
\int_0^1 x^2 dx = \frac{1}{3}
\```

Terminal Support

termula auto-detects your terminal and picks the best rendering mode.

termula -m kitty    # Force Kitty Graphics
termula -m iterm2   # Force iTerm2 inline images
termula -m unicode  # Force Unicode art
termula -m inline   # Force inline Unicode symbols
termula -m off      # Pass-through (no rendering)

Delimiters

Inline $...$ is off by default to avoid false positives with shell variables like $HOME. Enable with termula -d all.

Architecture

                    stdin / pty
                        │
              ┌─────────▼──────────┐
              │      Scanner       │
              │                    │
              │  $$  ```math  \[   │
              │  \(    $           │
              │                    │
              │  ANSI passthrough  │
              │  50ms $ timeout    │
              └────────┬───────────┘
                       │
              ┌────────▼───────────┐
              │     Converter      │
              │                    │
              │  typst+mitex → PNG │
              │  utftex    → text  │
              │  symbols   → inline│
              └────────┬───────────┘
                       │
              ┌────────▼───────────┐
              │     Renderer       │
              │                    │
              │  Kitty Graphics    │
              │  iTerm2 inline     │
              │  Unicode art       │
              └────────┬───────────┘
                       │
                    stdout

Two operating modes:

• Pipe filter — stdin | termula — stream filter
• Wrapper — termula -- cmd — spawns in a pty, preserves interactivity (raw mode, SIGWINCH, signal forwarding)

Options

termula [OPTIONS] [-- <COMMAND>...]

Options:
  -m, --mode <MODE>           Rendering mode [default: auto]
                              [auto, kitty, iterm2, unicode, inline, off]
  -d, --delimiters <DEL>      Delimiters to detect [default: block,display]
                              [block, display, inline, all]
  -w, --width <COLS>          Max width for Unicode art
      --dark                  Force dark background
      --light                 Force light background
      --no-cache              Disable image cache
      --completions <SHELL>   Generate shell completions [bash, zsh, fish]
  -v, --verbose               Show debug info on stderr
  -h, --help                  Print help
  -V, --version               Print version

Configuration file

termula reads ~/.config/termula/config.toml (or $XDG_CONFIG_HOME/termula/config.toml). CLI args take precedence.

mode = "unicode"
delimiters = "all"
dark = true
width = 100

Contributing

Contributions welcome — see CONTRIBUTING.md for development setup and guidelines. Main repository: https://github.com/j-ito0625/termula.

MIT License — Made for the terminal-native developer.