ty-lsp for Claude Code

Reference implementation of ty LSP plugin for Claude Code.

ty is an extremely fast Python type checker and language server from Astral (creators of Ruff and uv), written in Rust. This plugin enables ty integration with Claude Code for blazing-fast Python type checking.

⚡ Performance

Performance comparison on a 2,092-line typed Python codebase (16 files):

Type Checker	Mode	Avg Time	Performance
ty	default	0.43s	2.2x faster
Pyright	basic	0.95s	baseline

Key Findings:

• ✅ ty is consistently 2.2x faster than Pyright
• ✅ Both catch real type errors effectively
• ⚠️ ty is still in beta (v0.0.10) - strict mode planned for 2026
• ✅ Excellent for LSP usage where responsiveness matters

📋 Prerequisites

You need uv installed to run ty:

# Install uv (if not already installed)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify ty works
uvx ty@latest --version

🚀 Installation

Option 1: Install from Local Directory (Recommended for Testing)

# Clone this repository
git clone https://github.com/YOUR_USERNAME/ty-lsp-claude-code.git
cd ty-lsp-claude-code

# Install the plugin in Claude Code
claude plugin install .

Option 2: Test Without Installing

For testing without permanent installation:

# Run Claude Code with this plugin
claude --plugin-dir /path/to/ty-lsp-claude-code

Option 3: Manual Installation

1. Copy this directory to ~/.claude/plugins/local/ty-lsp/
2. Add to your ~/.claude/settings.json:

{
  "enabledPlugins": {
    "ty-lsp@local": true
  }
}

🔧 Configuration

Basic Configuration

No additional configuration needed - ty will automatically discover your project settings from pyproject.toml.

Advanced Configuration

Create or update pyproject.toml in your project root:

[tool.ty.environment]
python-version = "3.12"

[tool.ty.rules]
# Configure individual rules (see: https://docs.astral.sh/ty/rules/)
invalid-assignment = "error"
invalid-argument-type = "error"
invalid-return-type = "error"

Disabling Pyright (Optional)

If you want to use ty exclusively and disable Pyright:

File: ~/.claude/settings.json

{
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": false,
    "ty-lsp@local": true
  }
}

📊 Benchmark Details

Test Environment

• Benchmark: Synthetic Python codebase
• Files: 16 Python files (.py)
• Lines: 2,092 lines of code
• Features: Complex generics, async patterns, TypedDict, dataclasses, protocols

Methodology

• 5 runs per type checker, averaged
• Cold start included in first run
• Same codebase tested with both checkers
• Comparable modes (Pyright basic vs ty default)

Full Results

Pyright (basic mode):

Run 1: 1.442s
Run 2: 0.956s
Run 3: 0.945s
Run 4: 0.960s
Run 5: 0.947s
Average: 0.950s

ty (default mode):

Run 1: 0.444s
Run 2: 0.426s
Run 3: 0.445s
Run 4: 0.408s
Run 5: 0.423s
Average: 0.429s

Speedup: 2.21x faster

⚠️ Current Limitations

ty is in beta (v0.0.10) as of January 2025:

1. No Strict Mode Yet: ty doesn't enforce type annotations on all functions (planned for 2026 v1.0)
2. Limited Rule Set: ~95 rules implemented, more coming
3. Early Stage: May have rough edges compared to mature Pyright

Recommendation: Great for early adopters and performance-critical LSP usage. For production strict typing, continue using Pyright until ty 1.0.

🔗 Related Links

• ty Documentation
• ty GitHub Repository
• ty Issue #2230 - Claude Code Support
• Claude Code Documentation
• Astral

📝 Plugin Structure

This plugin follows the Claude Code plugin specification:

ty-lsp-claude-code/
├── .claude-plugin/
│   └── plugin.json      # Plugin manifest with LSP configuration
└── README.md            # This file

The LSP configuration in plugin.json:

{
  "lspServers": {
    "ty": {
      "command": "uvx",
      "args": ["ty@latest", "server"],
      "extensionToLanguage": {
        ".py": "python",
        ".pyi": "python"
      }
    }
  }
}

🤝 Contributing

This is a reference implementation created in response to astral-sh/ty#2230.

Suggestions and improvements welcome! Please open an issue or PR.

📄 License

MIT License - See ty repository for ty's license terms.

🙏 Acknowledgments

• Astral team for creating ty, Ruff, and uv
• Anthropic for Claude Code
• Community feedback on the ty GitHub issue