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.

This is a recurring, unresolved pain in the Claude Code ecosystem: worktree/venv breakage keeps being reported upstream — anthropics/claude-code#31391 (closed as not planned), astral-sh/claude-code-plugins#18 (open), anthropics/claude-code#58365 — while the official pyright plugin remains a single pyright-langserver spawn with no environment handling. typemux-cc exists to solve the environment-lifecycle side of this problem for Python.

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.

Frozen capabilities on cold start — initialize always answers immediately with empty capabilities, on every startup, regardless of whether a .venv exists yet — the first backend, like every other, is created lazily on the first venv-resolving message (#140: a synchronous pre-spawned-backend handshake here used to permanently wedge Claude Code 2.1.207's LSP client, still reproducible on 2.1.211). That advertisement stays frozen for the session — verified with Claude Code 2.1.207 that the client keeps sending LSP requests regardless, so nothing is gated (see Frozen Empty Capabilities).

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

How the Installer Verifies Binaries

The plugin's SessionStart hook downloads the prebuilt binary for your platform from this repository's GitHub Releases over HTTPS, pinned to the plugin's own version tag (never "latest"). Before the downloaded binary is executed or activated, the installer:

1. Verifies its SHA256 checksum against the .sha256 asset published alongside it by the release workflow
2. Confirms the binary reports the expected version

On any failure it keeps the previously working binary and prints an explicit warning, or fails loudly if no binary exists yet. Binaries are built from the tagged commit by GitHub Actions — nothing is built or fetched from anywhere else.

Method B: Local Build (For Developers)

Requires Rust 1.88 or later. Running the full test suite (cargo test / make ci) additionally requires jq — it's used by scripts/check-versions.sh to validate the release version across Cargo.toml, Cargo.lock, and the plugin manifests. Install it with brew install jq (macOS) or apt-get install -y jq (Debian/Ubuntu). make ci fails fast with a clear error if jq is missing.

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

An invalid value for a numeric variable above (e.g. TYPEMUX_CC_FANOUT_TIMEOUT=5s) fails startup with an explicit error instead of silently falling back to the default. TYPEMUX_CC_POOL_SWEEP_INTERVAL=0 also fails startup — unlike the other vars, 0 isn't a valid "disable" sentinel here; use --backend-ttl 0 / TYPEMUX_CC_VENV_CHECK_INTERVAL=0 to disable the sweep's individual jobs instead.

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

For self-diagnosis (--doctor), LSP not working, plugin update issues, .venv not switching, and the "Project root is gitignored" warning, see:

docs/TROUBLESHOOTING.md

Known Limitations

Architecture

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

docs/ARCHITECTURE.md

Privacy

typemux-cc runs entirely locally and collects no data. The only network access is the version-pinned, checksum-verified binary download from GitHub Releases at install time. See PRIVACY.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.