typemux-cc

Python type-checker LSP multiplexer for Claude Code — pyright, ty, pyrefly

Quickstart ◆ Problems Solved ◆ Backends ◆ Installation ◆ Typical Use Case ◆ Architecture

Claude Code's official pyright plugin spawns a single LSP backend at startup and holds onto it. If .venv doesn't exist yet — or you create a new one later — it never picks it up. You have to restart Claude Code.

This is especially painful with git worktrees, now common in AI-assisted development: you spin up a fresh worktree, create .venv, and then must restart Claude Code just to get type-checking.

typemux-cc is a Python LSP proxy that fixes this — .venv changes are reflected within your running session, no restarts required.

Quickstart

# 1. Install a backend (pyright recommended)
npm install -g pyright

# 2. Disable the official pyright plugin
/plugin disable pyright-lsp@claude-plugins-official

# 3. Add marketplace and install
/plugin marketplace add K-dash/typemux-cc
/plugin install typemux-cc@typemux-cc-marketplace

# 4. Restart Claude Code (initial installation only)

For ty/pyrefly, set TYPEMUX_CC_BACKEND in your config.

Problems Solved

• ⚡ Late .venv creation (worktrees, hooks) — Spin up a git worktree, create .venv later, and typemux-cc picks it up on the next file open. No Claude Code restart needed.
• 🔄 Multi-project venv switching (monorepos) — typemux-cc keeps a per-.venv backend pool and routes requests to the correct one. Switching between projects is instant.
• 🔀 Multi-backend support — Not locked into pyright. Choose between pyright, ty, or pyrefly — switch via a single env var.

Why LSP over text search? In monorepos, grep returns false positives from same-named types across projects. LSP resolves references at the type-system level. See real-world benchmarks.

Supported Backends

Requirements

Supported OS

[!Note]
Windows is currently unsupported (due to path handling differences).
Intel macOS users must build from source (prebuilt binaries are arm64 only).

Prerequisites

• One of the supported LSP backends available in PATH:
  • pyright-langserver (install via npm install -g pyright or pip install pyright)
  • ty (install via pip install ty or uvx ty)
  • pyrefly (install via pip install pyrefly)
• Git (used to determine .venv search boundary, works without it)

Installation

[!Note]
Claude Code restart is required only for initial installation. After installation, .venv creation and switching no longer require restarts.

Prerequisites

1. Install your preferred LSP backend

# pyright (default, recommended)
npm install -g pyright

# ty (by the creators of uv)
pip install ty

# pyrefly (by Meta)
pip install pyrefly

2. Disable Official pyright Plugin

[!Important]
You must disable the official pyright plugin. Having both enabled causes conflicts.

/plugin disable pyright-lsp@claude-plugins-official

Method A: From GitHub Marketplace (Recommended)

[!Note]
Installation uses GitHub API and curl. It may fail in offline environments or under rate limiting.

# 1. Add marketplace
/plugin marketplace add K-dash/typemux-cc

# 2. Install plugin
/plugin install typemux-cc@typemux-cc-marketplace

# 3. Restart Claude Code (initial installation only)

After installation, verify in ~/.claude/settings.json:

{
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": false,
    "typemux-cc@typemux-cc-marketplace": true
  }
}

Update / Uninstall

# Update
/plugin update typemux-cc@typemux-cc-marketplace

# Uninstall
/plugin uninstall typemux-cc@typemux-cc-marketplace
/plugin marketplace remove typemux-cc-marketplace

Method B: Local Build (For Developers)

Requires Rust 1.75 or later.

git clone https://github.com/K-dash/typemux-cc.git
cd typemux-cc
cargo build --release

/plugin marketplace add /path/to/typemux-cc
/plugin install typemux-cc@typemux-cc-marketplace
# Restart Claude Code (initial installation only)

Usage

Automatically starts as a Claude Code plugin — no manual setup required.

Configuration

Settings are stored in ~/.config/typemux-cc/config. The file uses KEY=VALUE format (shell expansion is not supported):

mkdir -p ~/.config/typemux-cc
cat > ~/.config/typemux-cc/config << 'EOF'
# Select backend (pyright, ty, or pyrefly)
TYPEMUX_CC_BACKEND=pyright

# Enable file logging
TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log
EOF

Note: export KEY=VALUE syntax is also accepted for compatibility with older config files.

Settings priority: CLI flag > environment variable > config file > default

Typical Use Case

Git Worktree (AI-Assisted Development)

A common workflow with AI coding agents:

my-project/                    # main worktree
├── .venv/
└── src/main.py

my-project-worktree/           # new worktree (no .venv yet)
└── src/main.py

With the official plugin, step 3 would require restarting Claude Code. With typemux-cc, it just works.

Monorepo Structure

my-monorepo/
├── project-a/
│   ├── .venv/          # project-a specific virtual environment
│   └── src/main.py
├── project-b/
│   ├── .venv/          # project-b specific virtual environment
│   └── src/main.py
└── project-c/
    ├── .venv/          # project-c specific virtual environment
    └── src/main.py

Operation Sequence

What Actually Happens

When Claude Code moves from project-a/main.py to project-b/main.py:

1. Proxy detects different .venv (project-a/.venv → project-b/.venv)
2. Checks the backend pool — project-b/.venv not found
3. Spawns new backend with VIRTUAL_ENV=project-b/.venv (session 2)
4. Session 1 (project-a) stays alive in the pool — no restart
5. Restores open documents under project-b/ to session 2
6. Clears diagnostics for documents outside project-b/
7. All LSP requests for project-b files now use project-b dependencies

When Claude Code returns to project-a/main.py later, session 1 is still in the pool — zero restart overhead.

Backends are evicted only when the pool is full (LRU) or after idle timeout (TTL, default 30 min).

From the user's perspective: Nothing visible happens. LSP just works.

Environment Variables

Each backend process is spawned with VIRTUAL_ENV and PATH set to point at the detected .venv. These are only applied to the child backend process — your shell environment and system PATH are never modified.

Troubleshooting

Self-Diagnosis (--doctor)

Run --doctor to dump configuration, environment, and system info at a glance:

# Find the binary in the plugin cache, then run --doctor
ls ~/.claude/plugins/cache/typemux-cc-marketplace/typemux-cc/
# → 0.2.9
~/.claude/plugins/cache/typemux-cc-marketplace/typemux-cc/0.2.9/bin/typemux-cc --doctor

The binary reads ~/.config/typemux-cc/config directly, so your settings are reflected in the output:

typemux-cc v0.2.9

Config file:
  Path              /Users/foo/.config/typemux-cc/config
  Status            loaded

Configuration:
  backend         pyright              (default)
  max_backends    8                    (default)
  backend_ttl     1800                 (default)
  warmup_timeout  2                    (default)
  fanout_timeout  5                    (default)
  log_file        /tmp/typemux-cc.log  (config: /Users/foo/.config/typemux-cc/config)

Environment:
  Backend binary    pyright-langserver
    Path            /usr/local/bin/pyright-langserver
    Version         pyright 1.1.350
  Git toplevel      /Users/foo/project
  Fallback venv     /Users/foo/project/.venv

System:
  OS                macos (Darwin 24.0.0)
  Arch              aarch64

Add --json for machine-readable output:

~/.claude/plugins/cache/typemux-cc-marketplace/typemux-cc/0.2.9/bin/typemux-cc --doctor --json

LSP Not Working

Tip: Run --doctor first to check your configuration and backend availability. For detailed logs, add TYPEMUX_CC_LOG_FILE=/tmp/typemux-cc.log to your config.

# Quick self-diagnosis (replace version number as needed)
~/.claude/plugins/cache/typemux-cc-marketplace/typemux-cc/0.2.9/bin/typemux-cc --doctor
cat ~/.claude/settings.json | grep typemux   # Check plugin settings
tail -100 /tmp/typemux-cc.log               # Check logs (if file logging enabled)

Plugin Update Not Taking Effect

Due to a known Claude Code issue, /plugin update may not refresh the cached plugin files. If you still see the old version after updating, manually clear the cache:

# 1. Remove cached plugin
rm -rf ~/.claude/plugins/cache/typemux-cc-marketplace/

# 2. Reinstall
/plugin install typemux-cc@typemux-cc-marketplace

# 3. Restart Claude Code

.venv Not Switching

• Verify .venv/pyvenv.cfg exists
• Verify file is within git repository
• Use RUST_LOG=trace for detailed venv search logs

[!Note]
If .venv didn't exist when a file was first opened, typemux-cc automatically re-searches for it on the next LSP request. No need to reopen the file.

Known Limitations

Architecture

For design philosophy, state transitions, and internal implementation details, see:

ARCHITECTURE.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.