Environment Variables

Complete reference for all typemux-cc environment variables

Environment variables provide an alternative way to configure typemux-cc. They are especially useful when running as a Claude Code plugin or in containerized environments.

Configuration Variables

All CLI flags have corresponding environment variables. CLI flags take precedence when both are set.

Core Configuration

Variable	Type	Default	Description
TYPEMUX_CC_BACKEND	enum	pyright	LSP backend type: pyright, ty, or pyrefly
TYPEMUX_CC_LOG_FILE	path	(not set)	Path to log file. When set, logs to both stderr and file
TYPEMUX_CC_MAX_BACKENDS	integer	8	Maximum concurrent backend processes (minimum: 1)
TYPEMUX_CC_BACKEND_TTL	integer	1800	Backend TTL in seconds. Set to 0 to disable TTL eviction
TYPEMUX_CC_WARMUP_TIMEOUT	integer	2	Warmup timeout in seconds. Set to 0 to disable warmup queueing

Logging Configuration

Variable	Type	Default	Description
RUST_LOG	string	typemux_cc=debug	Log level filter. See Logging Levels

Variable Details

TYPEMUX_CC_BACKEND

Selects which LSP backend to use for Python type checking.

Valid values:

• pyright - Microsoft’s Pyright (default)
• ty - Google’s ty
• pyrefly - Astral’s pyrefly

Example:

export TYPEMUX_CC_BACKEND=ty
typemux-cc

TYPEMUX_CC_LOG_FILE

Path to log file for debug output. When set, logs are written to both stderr and the specified file.

Example:

export TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log
typemux-cc

TYPEMUX_CC_MAX_BACKENDS

Maximum number of concurrent LSP backend processes. The proxy maintains one backend per .venv. When the pool is full, the least recently used backend is evicted.

Valid range: Minimum 1, no upper limit

Example:

# Large monorepo with many projects
export TYPEMUX_CC_MAX_BACKENDS=20
typemux-cc

TYPEMUX_CC_BACKEND_TTL

Backend time-to-live in seconds. Idle backends are automatically evicted after this timeout. Set to 0 to disable TTL-based eviction (backends only evicted via LRU when pool is full).

Example:

# Keep backends alive for 1 hour
export TYPEMUX_CC_BACKEND_TTL=3600
typemux-cc

# Disable TTL eviction
export TYPEMUX_CC_BACKEND_TTL=0
typemux-cc

TYPEMUX_CC_WARMUP_TIMEOUT

Maximum time (in seconds) to wait for backend index warmup before forwarding queued requests.

After spawning, backends need time to build their cross-file index. Requests like textDocument/definition and textDocument/references are queued until:

1. Backend sends $/progress notification with kind: "end", OR
2. Timeout expires (fail-open: forward requests anyway)

Set to 0 to disable warmup queueing entirely (all requests forwarded immediately).

Default: 2 seconds

Example:

# Wait up to 5 seconds for index warmup
export TYPEMUX_CC_WARMUP_TIMEOUT=5
typemux-cc

# Disable warmup queueing (send all requests immediately)
export TYPEMUX_CC_WARMUP_TIMEOUT=0
typemux-cc

This variable is not available as a CLI flag. It must be set via environment variable.

RUST_LOG

Controls log level and filtering. Accepts standard Rust tracing directives.

Default: typemux_cc=debug

Example:

# Debug level (default)
export RUST_LOG=typemux_cc=debug

# Info level only
export RUST_LOG=typemux_cc=info

# Trace everything (very verbose)
export RUST_LOG=trace

# Multiple targets
export RUST_LOG=typemux_cc=debug,tower_lsp=info

Logging Levels

Level	Use Case
trace	All search steps, detailed message routing
debug	Default. Venv search details, LSP method names
info	Venv switches, session info, warmup transitions
warn	Unexpected conditions, recoverable errors
error	Fatal errors, backend crashes

Configuration Precedence

When multiple configuration sources are present:

1. CLI flags (highest priority)
2. Environment variables
3. Default values (lowest priority)

Example:

# Environment variable sets default
export TYPEMUX_CC_MAX_BACKENDS=10

# CLI flag overrides environment variable (uses 16)
typemux-cc --max-backends 16

Persistent Configuration

When running as a Claude Code plugin, create a config file to persist settings:

Location: ~/.config/typemux-cc/config

Setup:

mkdir -p ~/.config/typemux-cc
cat > ~/.config/typemux-cc/config << 'EOF'
# Backend selection
export TYPEMUX_CC_BACKEND="ty"

# Enable logging
export TYPEMUX_CC_LOG_FILE="/tmp/typemux-cc.log"

# Pool configuration
export TYPEMUX_CC_MAX_BACKENDS=12
export TYPEMUX_CC_BACKEND_TTL=3600

# Warmup timeout
export TYPEMUX_CC_WARMUP_TIMEOUT=3

# Logging level
export RUST_LOG="typemux_cc=debug"
EOF

Restart Claude Code to apply changes.

Usage Examples

Minimal Configuration

# Use defaults (pyright, 8 backends, 30min TTL)
typemux-cc

Enable Logging

export TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log
export RUST_LOG=debug
typemux-cc

Large Monorepo

export TYPEMUX_CC_MAX_BACKENDS=20
export TYPEMUX_CC_BACKEND_TTL=7200  # 2 hours
export TYPEMUX_CC_LOG_FILE=/var/log/typemux-cc.log
typemux-cc

Use ty Backend

export TYPEMUX_CC_BACKEND=ty
typemux-cc

Disable Warmup Queueing

# Send all requests immediately (no warmup delay)
export TYPEMUX_CC_WARMUP_TIMEOUT=0
typemux-cc

Combined Configuration

export TYPEMUX_CC_BACKEND=ty
export TYPEMUX_CC_MAX_BACKENDS=12
export TYPEMUX_CC_BACKEND_TTL=3600
export TYPEMUX_CC_WARMUP_TIMEOUT=3
export TYPEMUX_CC_LOG_FILE=~/.local/state/typemux-cc.log
export RUST_LOG=info
typemux-cc

Monitoring and Debugging

Real-time Log Monitoring

# Watch logs as they happen
export TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log
tail -f /tmp/typemux-cc.log

Backend Pool Activity

# Track backend lifecycle events
grep -E "(Creating new backend|Evicting|Backend warmup)" /tmp/typemux-cc.log

Warmup Transitions

# Monitor warmup state changes
grep "warmup" /tmp/typemux-cc.log

Session Tracking

# View session lifecycle
grep "session=" /tmp/typemux-cc.log | grep -E "(Starting|completed)"

See Also

• CLI Flags - Command-line flag reference
• Configuration - Detailed configuration strategies
• Logging - Comprehensive logging setup and debugging