Beautiful math, right in your terminal.
A Rust math renderer for live CLI output. Built for stock Codex in Ghostty.
Quick start · Performance · Comparison · Configuration · Contributing
Read equations where you work. TermiTex turns LaTeX in CLI output into beautifully typeset math, with native Rust rendering and equations that follow the conversation as you scroll. Launch it with one command—no custom Codex build.
- Native by default. RaTeX renders with embedded math fonts; no Node.js or TFormula runtime required.
- Rendering stays off the input loop. Cached equations move without being typeset again.
- Two layouts. Compact math with native prose for Codex, or centered overlays that preserve source cells.
- Optional MathJax. Select it for its appearance or extensions such as physics
\dv.
Maxwell’s equations, rendered directly in Codex CLI.
On macOS or Linux, install the native binary:
curl -fsSL https://raw.githubusercontent.com/tingkai-c/TermiTex/main/install.sh -o /tmp/termitex-install.sh
sh /tmp/termitex-install.shThe installer verifies release checksums and installs to ~/.local/bin. On a first install it offers optional shell setup for Codex, Claude Code, or both. Existing aliases and functions are preserved. Open a new shell after setup, then run termitex codex or termitex claude (or the chosen aliases).
Rerun the installer to update. An already-current version is left alone; --force reinstalls it. Updates and reinstalls preserve shell configuration. No Rust or Node is required. Linux binaries need a compatible glibc system; the installer checks that the binary runs before replacing an existing installation. Installer options, manual downloads, and removal.
Alternatively, on macOS with Homebrew:
brew install tingkai-c/tap/termitex
termitex codexHomebrew handles the build and dependencies through our official tap. No Node or npm needed.
To update later:
brew update
brew upgrade termitexBuild from source instead
Requires Git and a recent Rust toolchain (tested with 1.95).
git clone https://github.com/tingkai-c/TermiTex.git
cd TermiTex
cargo build --release --locked
./target/release/termitex codexWrap an app directly:
termitex codex
termitex claude
termitex --layout compatibility pythonArguments after the app name pass through to that app. termitex codex disables Codex's built-in math rendering automatically. termitex claude appends a short instruction requesting literal LaTeX with \(...\) and \[...\], unless you supply your own append prompt. Running termitex alone shows usage. Use termitex -- command ... for literal argument passthrough.
Codex and Claude Code have dedicated input-area rules to keep drafts as text. Other commands use generic math detection; choose compatibility mode for applications that manage their own screen layout.
One graphics backend targets Ghostty, Kitty, WezTerm, iTerm2, and Konsole, with automatic capability detection and readable source text when graphics are unavailable.
termitex doctorTerminal setup & verification status · Architecture. Available in v0.2.0.
TermiTex vs TFormula on the same headless terminal workload. Each trial renders 12 equations, then repeats them.
| Metric · median across 5 trials | TermiTex 0.1.0 · native, compatibility mode | TFormula 0.3.1 · default settings |
|---|---|---|
| Launch → first image placement | 18.57 ms | 361.11 ms |
| New equation → placement, after first render | 5.19 ms | 203.85 ms |
| Repeated equation → placement | 0.49 ms | 196.75 ms |
| Peak sampled process-tree RSS | 20.88 MiB | 184.22 MiB |
| Cases producing validated PNG placements per trial | 24 / 24 | 24 / 24 |
Methodology, scope & reproduction · Raw results
Choose the workflow that fits your terminal.
| Tool | Workflow | Renderer |
|---|---|---|
| TermiTex | Live CLI math; compact layout or centered, source-preserving overlays | Native RaTeX by default; optional MathJax |
| TFormula | Live agent overlays and a document reader | MathJax |
| TXM | Expression rendering and library/editor integration | Rust rendering engine |
Create ~/.config/termitex/config.toml (or $XDG_CONFIG_HOME/termitex/config.toml):
renderer = "ratex" # "ratex" or "mathjax"
layout = "compact" # "compact" or "compatibility"| Setting | Default | Override |
|---|---|---|
| Renderer | ratex |
--renderer mathjax or TERMITEX_RENDERER=mathjax |
| Layout | compact |
--layout compatibility or TERMITEX_LAYOUT=compatibility |
| Foreground / background | Detected terminal theme | TERMITEX_FG / TERMITEX_BG |
| Statistics file | Disabled | TERMITEX_STATS=/tmp/termitex-stats.json |
Precedence: CLI > environment > config > default. Options after --, or after the child command starts, belong to that program. See config.example.toml.
| Behavior | Compact (default) | Compatibility (opt-in) |
|---|---|---|
| Inline math | Fits rendered width; surrounding prose moves left | Centered horizontally in the original source span; text baseline retained |
| Display math | Centered in its detected block | Centered in its detected block |
| Underlying terminal text | Projected cells replace visible source | Original source cells remain intact |
| Wrapped inline formulas | Joined when fully visible, up to nine source rows | Left as source to avoid covering neighboring prose |
| Intended use | Codex in Ghostty | Preserving source text and coordinates |
The Homebrew package includes the native renderer only. For MathJax, use the source-build instructions above, keep the checkout, and install Node.js 20+. From that checkout:
npm ci --ignore-scripts
./target/release/termitex --renderer mathjax codexChoose RaTeX for native rendering or MathJax for its appearance and extensions. Renderer details.
Terminal support · Architecture · Rendering & compatibility · Benchmarks · Example configuration
Bug reports are most useful with the terminal and OS versions, backend/layout, a minimal formula or redraw sequence, and expected versus actual output. Open an issue.
cargo test --locked
cargo fmt --check
python3 tests/installer.pyThe Rust tests cover detection, layout, configuration, worker recovery, and headless PTY scrolling/resizing. Native image checks exercise 31 representative renders and five invalid/unsupported inputs; compatibility checks verify centering. The Rust tests need neither Python nor Pillow. Installer tests and historical benchmark scripts use Python.
After installing npm dependencies, also run:
cargo test --locked --test workers mathjax -- --ignored
cargo test --locked --test pty mathjax -- --ignored
node tests/backend_pixels.mjs
node tests/cache.mjsSet TERMITEX_TEST_ARTIFACTS=/tmp/termitex-qa to save PNGs and source requests for inspection.
TermiTex is MIT licensed. Native rendering uses RaTeX, pinned to 776c1d37bafa3bf445a0ab9377c55fe77f7a0133; font notices are in licenses/. Include these notices when redistributing the native binary.
Inspired by TFormula, by Mike Wang. Small MathJax geometry, SVG-dimension, and TeX-compatibility helpers were adapted under MIT; see the retained notice. No TFormula package, process, configuration, or cache is used. MathJax/resvg retain their own licenses.