> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/K-dash/typemux-cc/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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**:

```bash theme={null}
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**:

```bash theme={null}
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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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
```

<Note>
  This variable is **not** available as a CLI flag. It must be set via environment variable.
</Note>

### RUST\_LOG

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

**Default**: `typemux_cc=debug`

**Example**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```bash theme={null}
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

```bash theme={null}
# Use defaults (pyright, 8 backends, 30min TTL)
typemux-cc
```

### Enable Logging

```bash theme={null}
export TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log
export RUST_LOG=debug
typemux-cc
```

### Large Monorepo

```bash theme={null}
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

```bash theme={null}
export TYPEMUX_CC_BACKEND=ty
typemux-cc
```

### Disable Warmup Queueing

```bash theme={null}
# Send all requests immediately (no warmup delay)
export TYPEMUX_CC_WARMUP_TIMEOUT=0
typemux-cc
```

### Combined Configuration

```bash theme={null}
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

```bash theme={null}
# Watch logs as they happen
export TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log
tail -f /tmp/typemux-cc.log
```

### Backend Pool Activity

```bash theme={null}
# Track backend lifecycle events
grep -E "(Creating new backend|Evicting|Backend warmup)" /tmp/typemux-cc.log
```

### Warmup Transitions

```bash theme={null}
# Monitor warmup state changes
grep "warmup" /tmp/typemux-cc.log
```

### Session Tracking

```bash theme={null}
# View session lifecycle
grep "session=" /tmp/typemux-cc.log | grep -E "(Starting|completed)"
```

## See Also

* [CLI Flags](/reference/cli-flags) - Command-line flag reference
* [Configuration](/configuration/environment-variables) - Detailed configuration strategies
* [Logging](/configuration/logging) - Comprehensive logging setup and debugging