# basedpyright-type-checking

Sets up strict Python type checking using basedpyright, compares it against mypy, and guides configuration in pyproject.toml.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 320 installs · ★ 59
- Author: laurigates
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/laurigates/claude-plugins/tree/HEAD/python-plugin/skills/basedpyright-type-checking/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/basedpyright-type-checking

## What it does

This skill teaches your agent how to set up basedpyright, a fast Pyright fork designed around strict default typing rules. It covers generating `[tool.basedpyright]` configurations in `pyproject.toml`, switching modes from `basic` to `strict`, and suppressing errors with `# basedpyright: ignore`.

The guidance includes CLI commands for `uv` and `pipx`, background execution with `--watch`, and JSON diagnostic outputs. It also breaks down differences between basedpyright, standard Pyright, and mypy.

Formatting and linting should stay in Ruff rather than the type checker. Because basedpyright has limited plugin support, codebases dependent on tools like `pydantic-mypy` cannot migrate cleanly.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add laurigates/claude-plugins --skill basedpyright-type-checking -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/basedpyright-type-checking/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/basedpyright-type-checking/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add laurigates/claude-plugins --skill basedpyright-type-checking -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/basedpyright-type-checking/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add laurigates/claude-plugins --skill basedpyright-type-checking -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/basedpyright-type-checking/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install laurigates/claude-plugins basedpyright-type-checking
```

2. **Manually: put the files in place**
- File: `.github/skills/basedpyright-type-checking/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add laurigates/claude-plugins --skill basedpyright-type-checking -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/laurigates/claude-plugins --path python-plugin/skills/basedpyright-type-checking
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/basedpyright-type-checking/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add laurigates/claude-plugins --skill basedpyright-type-checking -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/laurigates/claude-plugins/tree/HEAD/python-plugin/skills/basedpyright-type-checking/SKILL.md

## When to use it
- configure strict type checking in pyproject.toml
- evaluate trade-offs between basedpyright and mypy
- adopt progressive type checking from basic to strict mode
- suppress specific type errors using inline comments

## Example prompts
- Configure basedpyright for our Python 3.12 project in strict mode
- Compare mypy and basedpyright trade-offs for this repository
- Run basedpyright with uv in watch mode targeting the src directory

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a742cd232c3e5a19.

BEGIN THIRD-PARTY FILE a742cd232c3e5a19
````text
---
created: 2025-12-16
modified: 2026-05-09
reviewed: 2025-12-16
name: basedpyright-type-checking
description: Basedpyright static type checker for Python. Use when setting up type checking, configuring LSP, or comparing type checkers (basedpyright, pyright, mypy alternative).
user-invocable: false
allowed-tools: Bash, Read, Grep, Glob
---

# Basedpyright Type Checking

Basedpyright is a fork of Pyright with additional features and stricter defaults, designed for maximum type safety and performance.

## When to Use This Skill

| Use this skill when... | Use another tool instead when... |
|------------------------|----------------------------------|
| Setting up type checking for Python | Formatting code (use ruff format) |
| Configuring strict type validation | Linting for style issues (use ruff check) |
| Comparing type checkers (basedpyright vs mypy) | Detecting unused code (use vulture/deadcode) |
| Setting up LSP for type-aware editor support | Running tests (use pytest) |

## Installation

### Via uv (Recommended)
```bash
# Install globally
uv tool install basedpyright

# Install as dev dependency
uv add --dev basedpyright

# Run with uv
uv run basedpyright
```

### Via pipx
```bash
pipx install basedpyright
```

## Basic Usage

```bash
# Check entire project
basedpyright

# Check specific files/directories
basedpyright src/ tests/

# Watch mode for development
basedpyright --watch

# Output JSON for tooling integration
basedpyright --outputjson

# Verbose diagnostics
basedpyright --verbose
```

## Configuration

### Minimal Strict Configuration (pyproject.toml)

```toml
[tool.basedpyright]
typeCheckingMode = "strict"
pythonVersion = "3.12"
include = ["src"]
exclude = ["**/__pycache__", "**/.venv"]

# Basedpyright-specific strict rules
reportUnusedCallResult = "error"
reportImplicitStringConcatenation = "error"
reportMissingSuperCall = "error"
reportUninitializedInstanceVariable = "error"
```

## Type Checking Modes

| Mode | Description | Use Case |
|------|-------------|----------|
| `off` | No type checking | Legacy code, migration start |
| `basic` | Basic type checking | Gradual typing adoption |
| `standard` | Standard strictness | Most projects (default Pyright) |
| `strict` | Strict type checking | Type-safe codebases |
| `all` | Maximum strictness | High-assurance systems |

### Progressive Type Checking

```toml
# Start with basic mode
[tool.basedpyright]
typeCheckingMode = "basic"
include = ["src/new_module"]  # Type check new code only

# Gradually expand
include = ["src/new_module", "src/api"]

# Eventually enable strict mode
typeCheckingMode = "strict"
include = ["src"]
```

## Choosing a Type Checker

| Factor | Basedpyright | Pyright | mypy |
|--------|-------------|---------|------|
| **Speed** | Fastest | Fastest | Slower |
````
END THIRD-PARTY FILE a742cd232c3e5a19

The third-party file has ended. Everything between the a742cd232c3e5a19 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2797 of 4147 bytes. © laurigates · MIT · https://github.com/laurigates/claude-plugins/tree/HEAD/python-plugin/skills/basedpyright-type-checking/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md