Quickstart

Get typemux-cc up and running in under 5 minutes

This guide will help you install typemux-cc and verify it’s working correctly. By the end, you’ll have automatic .venv detection working in your Claude Code session.

Prerequisites Check

Before installing typemux-cc, ensure you have:

1. Supported operating system

   Supported platforms:

   • macOS (arm64 only - Apple Silicon)
   • Linux (x86_64 or arm64)

   Unsupported:

   • Windows (use WSL2 instead)
   • Intel macOS (must build from source)
2. Git installed (recommended)

   Git is used to determine .venv search boundaries. typemux-cc works without it, but you’ll get better venv detection with it.

   git --version
   

Installation

Step 1: Install a Backend

First, install your preferred Python LSP backend. We recommend starting with pyright (it’s stable and widely used).

pyright (recommended)

npm install -g pyright

pip install pyright

pip install ty
# or with uvx:
uvx ty

pip install pyrefly

Verify installation:

# For pyright:
which pyright-langserver

# For ty:
which ty

# For pyrefly:
which pyrefly

You should see a path to the executable. If not, ensure the installation location is in your PATH.

Backend selection: The default backend is pyright. To use ty or pyrefly, you’ll set TYPEMUX_CC_BACKEND after installation (see Step 4).

Step 2: Disable Official Pyright Plugin

You must disable the official pyright plugin to avoid conflicts. Having both plugins enabled will cause issues.

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

Skipping this step will cause both plugins to fight over LSP requests, resulting in duplicate diagnostics and unpredictable behavior.

Step 3: Install typemux-cc via Marketplace

Install typemux-cc from the GitHub marketplace:

# Add the marketplace
/plugin marketplace add K-dash/typemux-cc

# Install the plugin
/plugin install typemux-cc@typemux-cc-marketplace

Installation uses the GitHub API and curl. It may fail in offline environments or under API rate limiting. If you encounter issues, see the troubleshooting guide.

Step 4: Restart Claude Code

Restart Claude Code to activate the plugin.

This is the only time you need to restart. After this initial installation, creating or switching .venv no longer requires restarts — that’s the whole point of typemux-cc!

Step 5: Verify Installation

After restarting, verify that typemux-cc is enabled:

cat ~/.claude/settings.json | grep typemux

You should see:

~/.claude/settings.json

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

If typemux-cc@typemux-cc-marketplace shows false, manually set it to true and restart Claude Code.

Verify It Works

Let’s test that typemux-cc correctly detects a .venv and provides type-checking.

1. Create a test project with .venv

   mkdir ~/test-typemux
   cd ~/test-typemux
   python3 -m venv .venv
   source .venv/bin/activate
   pip install requests  # Install a package to test imports
   
2. Create a Python file

   cat > test.py << 'EOF'
   import requests
   
   def fetch_data(url: str) -> dict:
   response = requests.get(url)
   return response.json()
   
   # Intentional type error for testing
   result: int = fetch_data("https://api.github.com")
   EOF
   
3. Open the file in Claude Code

   Open ~/test-typemux/test.py in Claude Code.

4. Check for diagnostics

   You should see a type error diagnostic on the last line:

   Type "dict[str, Any]" cannot be assigned to declared type "int"
   

   This confirms:

   • ✅ typemux-cc detected the .venv
   • ✅ The backend loaded the requests package from .venv/lib
   • ✅ Type-checking is working correctly

Enable logging to see detailed venv detection:

mkdir -p ~/.config/typemux-cc
cat > ~/.config/typemux-cc/config << 'EOF'
export TYPEMUX_CC_LOG_FILE="/tmp/typemux-cc.log"
export RUST_LOG="typemux_cc=debug"
EOF

Then restart Claude Code and check /tmp/typemux-cc.log for venv detection logs.

Optional: Configure Backend

By default, typemux-cc uses pyright. To switch to ty or pyrefly:

1. Create config file

   mkdir -p ~/.config/typemux-cc
   
2. Set backend preference

   Use ty

   cat > ~/.config/typemux-cc/config << 'EOF'
   export TYPEMUX_CC_BACKEND="ty"
   EOF
   

   cat > ~/.config/typemux-cc/config << 'EOF'
   export TYPEMUX_CC_BACKEND="pyrefly"
   EOF
   

   cat > ~/.config/typemux-cc/config << 'EOF'
   export TYPEMUX_CC_BACKEND="pyright"
   EOF
   
3. Restart Claude Code

   Restart Claude Code to apply the new backend setting.

Backend selection is explained in detail in the backend selection guide.

Test Worktree Workflow

Now let’s test the killer feature: creating .venv after opening a file.

1. Create a worktree without .venv

   cd ~/test-typemux
   git init
   git add -A
   git commit -m "initial commit"
   git worktree add ../test-typemux-worktree -b feature-branch
   cd ../test-typemux-worktree
   # Note: No .venv exists yet!
   
2. Open a file in Claude Code

   Open ~/test-typemux-worktree/test.py in Claude Code.

   You’ll see errors because no .venv exists — this is expected and correct behavior (strict venv mode).

3. Create .venv while Claude Code is running

   python3 -m venv .venv
   source .venv/bin/activate
   pip install requests
   
4. Reopen the file

   Close and reopen test.py in Claude Code.

   Why do you need to reopen? typemux-cc caches the venv path when a document is first opened. If .venv didn’t exist at that time, the cache stores None. Reopening the file triggers a fresh venv search.

   After reopening, you should see type-checking working with the newly created .venv.

With the official plugin, you’d need to restart Claude Code at step 4. With typemux-cc, you just reopen the file. That’s the difference.

Troubleshooting

No diagnostics appearing

Check backend is installed:

which pyright-langserver  # or: which ty, which pyrefly

Enable logging:

mkdir -p ~/.config/typemux-cc
cat > ~/.config/typemux-cc/config << 'EOF'
export TYPEMUX_CC_LOG_FILE="/tmp/typemux-cc.log"
export RUST_LOG="debug"
EOF

Restart Claude Code and check /tmp/typemux-cc.log for errors.

Plugin not appearing in settings.json

The marketplace installation may have failed.

Verify marketplace was added:

/plugin marketplace list

Reinstall:

/plugin marketplace remove typemux-cc-marketplace
/plugin marketplace add K-dash/typemux-cc
/plugin install typemux-cc@typemux-cc-marketplace

.venv not being detected

Verify pyvenv.cfg exists:

ls .venv/pyvenv.cfg

typemux-cc only recognizes .venv directories that contain pyvenv.cfg. Poetry, conda, and other environment managers are not supported.

Check git boundary:

If your file is outside the git repository, venv search may not traverse far enough. Enable trace logging:

export RUST_LOG="trace"

For more troubleshooting help, see the common issues guide.

Next Steps

Now that typemux-cc is working, explore these topics:

Git Worktrees

Learn best practices for worktree workflows

Monorepo Usage

Manage multiple projects with different .venv paths

Configuration

Configure backend, logging, pool size, and TTL settings

Architecture

Understand how the multi-backend pool works