cclatex

Render LaTeX expressions in terminal output as inline images.

cclatex supports two runtime modes:

• Pipe mode (cclatex): transform stdin to stdout.
• PTY wrapper mode (cclatex-wrap): run interactive CLIs (such as oc, codex, claude) without shell hook injection.

Production recommendation: keep shell startup clean and use launcher/wrapper integration instead of auto-writing rc hooks.

Quick Start

Install globally:

npm install -g cclatex

For interactive AI CLIs (recommended):

cclatex-wrap -- opencode

For transparent daily use (no extra typing), add a local alias or launcher wrapper:

alias oc='cclatex-wrap -- opencode'

For one-shot pipe usage:

echo 'The formula $E=mc^2$' | cclatex

Run without install (pipe mode):

npx cclatex

How To Use

1) Pipe mode (simple streams)

echo 'The formula $E=mc^2$' | cclatex
opencode | cclatex

Pipe mode is best when your command naturally writes to stdout and does not require an interactive terminal.

2) PTY wrapper mode (interactive CLIs)

cclatex-wrap oc
cclatex-wrap codex
cclatex-wrap --font-size 24 --background "#ffffff" -- oc --model gpt-5

Use -- before wrapped command flags so wrapper flags and command flags are separated.

Wrapper options:

• --font-size <number> (default: 20)
• --background <color> (default: white)

PTY wrapper mode is the recommended way for interactive AI tools because it avoids shell hook side effects.

Optional Shell Hook (cclatex-hook)

Shell hook mode is optional and not the default recommendation. Use it only if you explicitly want rc-file injection.

If you want automatic wrapping via shell function injection:

cclatex-hook install --command oc --upstream opencode
source ~/.zshrc

Manage hook state:

cclatex-hook status --command oc
cclatex-hook remove --command oc

Bypass once:

CCLATEX_NO_WRAP=1 oc

Supported Terminal Output

terminal-image handles protocol detection and fallback (Kitty, iTerm2-compatible terminals, ANSI fallback).

Troubleshooting

• Command not found: verify wrapped command exists in PATH.
• Wrapper issues in CI/non-interactive shells: run cclatex-wrap in a real terminal session (TTY).
• If wrapped output shows raw $$...$$, your terminal/runtime likely fell back from PTY rendering to plain passthrough.
• Unexpected hook behavior: remove with cclatex-hook remove --command <name> and use cclatex-wrap instead.

Local Development

bun install
bun test
bun run typecheck
bun run build