Skip to main content

​
Overview

typemux-cc has several known limitations, most of which have practical workarounds. These limitations are often intentional design decisions to prevent silent failures.

​
Summary Table

LimitationImpactWorkaround
Windows unsupportedCannot run on native WindowsUse WSL2
macOS Intel unsupportedNo prebuilt binariesBuild from source
Fixed venv name (.venv only)Only detects .venv directoriesRename to .venv or create symlink
Symlinks may failCannot detect pyvenv.cfg through symlinksUse actual .venv directory
Late .venv creationCached as None if created after file openReopen file after creating .venv
setuptools editable installsImport resolution failsSwitch to hatchling/flit or configure extra-paths

​
Detailed Limitations

​
Windows Unsupported

typemux-cc does not run on native Windows due to path handling differences.
Issue:
  • Unix-like path assumptions (forward slashes, POSIX semantics)
  • Different environment variable conventions
  • Process spawning differences
Workaround: 
# Use WSL2 (Windows Subsystem for Linux)
wsl --install

# Install typemux-cc inside WSL2
# It will work exactly like on native Linux
WSL2 provides a full Linux environment and is fully supported by typemux-cc.

​
macOS Intel Unsupported (Prebuilt Binaries)

Intel macOS is supported when building from source. Only prebuilt binaries are arm64-only.
Issue:
  • Prebuilt binaries target arm64 (Apple Silicon) only
  • Limited demand for Intel builds
  • Build infrastructure costs
Workaround: 
# Build from source (requires Rust 1.75+)
git clone https://github.com/K-dash/typemux-cc.git
cd typemux-cc
cargo build --release

# Install as local plugin
/plugin marketplace add /path/to/typemux-cc
/plugin install typemux-cc@typemux-cc-marketplace
Building takes only a few minutes on modern hardware.

​
Fixed Virtual Environment Name

typemux-cc ONLY recognizes directories named .venv that contain a pyvenv.cfg file.
Issue:
  • Poetry, conda, and custom-named environments are not detected
  • This is intentional: prevents silently using the wrong environment
  • Design philosophy: “A silently lying LSP is the worst”
Supported:
  • ✅ .venv created with python -m venv
  • ✅ .venv created with uv venv
  • ✅ .venv created with virtualenv
Not Supported:
  • ❌ venv, env, .virtualenv (wrong name)
  • ❌ Poetry environments (different structure)
  • ❌ Conda environments (not a venv)
Workaround: 
# Option 1: Rename your venv
mv venv .venv

# Option 2: Create a symlink (may have issues - see next section)
ln -s my-custom-venv .venv

# Option 3: Create a new .venv
python -m venv .venv
# or
uv venv
The strict .venv requirement prevents accidentally using a wrong or stale environment, which would cause LSP to return incorrect type information.
Issue:
  • If .venv is a symlink, typemux-cc may fail to detect pyvenv.cfg
  • Symlink traversal behavior varies by OS
Affected Scenarios: 
# This may not work reliably
ln -s /path/to/actual-venv .venv
Workaround: 
# Don't use symlinks - copy or create actual .venv
python -m venv .venv
# or
cp -r /path/to/actual-venv .venv
If you must use a symlink and venv detection fails, create an actual .venv directory instead.

​
Late .venv Creation Cache Behavior

This is the most common issue in git worktree workflows.
Issue:
  • typemux-cc caches the venv path on first file open
  • If .venv doesn’t exist yet, it caches None
  • Subsequent requests use the cached value without re-searching
Scenario: 
# 1. Create worktree (no .venv yet)
git worktree add ../my-project-worktree feat/new-feature

# 2. Open file in Claude Code
# -> typemux-cc caches venv=None for this document

# 3. Create .venv
cd ../my-project-worktree
uv sync

# 4. LSP still doesn't work (cached as None)
Why This Happens: When a file is first opened, typemux-cc searches for .venv and caches the result. If .venv doesn’t exist, it caches None. Later requests reuse this cached value for performance, so creating .venv afterwards won’t trigger a new search. Workaround: 
# After creating .venv, reopen the file in Claude Code
# This clears the cache and triggers a fresh venv search
Verification: 
# Check logs for venv_path=None
RUST_LOG=trace TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log

# Look for:
# venv_path=None
Reopening the file is a one-time action per document. After the first reopen, the correct .venv will be cached.

​
Setuptools Editable Installs

This is NOT a typemux-cc bug. All Python LSP backends (pyright, ty, pyrefly) have this limitation.
Issue:
  • Setuptools-style editable installs use import hooks at runtime
  • LSP backends perform static analysis and cannot execute import hooks
  • Result: imports from editable packages fail to resolve
Affected: 
# This type of editable install won't work with LSP
pip install -e .  # if using setuptools
Root Cause: Setuptools editable installs create a .pth file that registers an import hook. This hook runs at Python runtime to redirect imports. LSP backends analyze code statically (without running Python), so they cannot execute these hooks. This affects: Workaround 1: Switch to modern build backend 
# pyproject.toml
[build-system]
requires = ["hatchling"]  # or "flit_core"
build-backend = "hatchling.build"  # or "flit_core.buildapi"
Modern build backends (hatchling, flit, pdm) create proper .pth files that LSP can resolve. Workaround 2: Configure backend extra-paths For pyright, add to pyrightconfig.json or pyproject.toml: 
{
  "executionEnvironments": [
    {
      "root": ".",
      "extraPaths": ["src"]
    }
  ]
}
For ty, add to pyproject.toml: 
[tool.ty]
extra-paths = ["src"]
For pyrefly, consult pyrefly documentation for path configuration.
This issue is fundamental to how setuptools editable installs work. It’s not specific to typemux-cc.

​
Debugging Tips

​
Enable Detailed Logging

# Set log file and trace level
export TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log
export RUST_LOG=trace

# Then check logs
tail -f /tmp/typemux-cc.log

​
Check Current Configuration

# Verify backend
echo $TYPEMUX_CC_BACKEND

# Check if backend is in PATH
which pyright-langserver  # or ty/pyrefly

# Verify .venv structure
ls -la .venv/pyvenv.cfg

​
Verify Plugin Installation

# Check Claude Code settings
cat ~/.claude/settings.json | grep typemux

# Should show:
# "typemux-cc@typemux-cc-marketplace": true

​
Feature Requests & Bug Reports

If you encounter limitations not listed here, please:
  1. Check the GitHub Issues
  2. Enable trace logging and gather logs
  3. Open a new issue with details
Some limitations are intentional design decisions (like strict .venv naming) to prevent silent failures. These are unlikely to change.