How to configure Claude Code with a Python type checker

Give Claude Code the same type-check command used by the project and CI. Add a language-server plugin if you want diagnostics during editing, or a bounded hook for a final check.

Prerequisites

• Claude Code and uv installed
• A project with a type checker installed as a development dependency
• A passing baseline, or a configured scope that excludes existing errors

Record the checker command

The handbook recommends Pyrefly for new projects. Keep the checker an existing project already uses unless migration is the task.

uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. For a new Pyrefly setup, run uv run pyrefly init and review the configuration it creates. Without configuration, Pyrefly selects a limited basic preset or migrates existing checker settings, so an unconfigured run does not check the same errors as an explicitly configured project.

Put the chosen command in CLAUDE.md:

## Type checking

This project uses Pyrefly. Run `uv run pyrefly check` after changes and
before reporting completion. Fix errors caused by the change. Report any
existing errors or blockers rather than suppressing them to pass a check.

Add a language server when useful

For ty, Astral’s plugin supplies a language server plus uv, Ruff, and ty skills:

/plugin marketplace add astral-sh/claude-code-plugins
/plugin install astral@astral-sh

For Pyright, Anthropic’s pyright-lsp plugin uses pyright-langserver from PATH. Install the server as a persistent tool first:

uv tool install pyright
pyright --version

The version command should print the installed Pyright version. The package also provides pyright-langserver. If the shell cannot find it, add uv’s tool executable directory to PATH and restart Claude Code. Then install the plugin inside Claude Code:

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

Use /plugin to confirm the plugin is enabled and inspect errors. Follow any reload prompt, then ask Claude to inspect a Python file. The server must be available in the environment hosting the session. A plugin installation alone does not verify that diagnostics are working.

A language server is optional. Pyrefly and mypy work through the project command and a final check without a plugin. Server diagnostics do not replace the full project check in CI.

Return failures through a bounded Stop hook

Follow write Claude Code hooks for Python projects to install the check-types.py hook and its exec-form configuration. It runs the project’s checker, returns failures on stderr with exit code 2, and uses stop_hook_active to allow a stop after one corrective attempt.

Replace the script’s command list with the chosen project command. For example, a ty project uses ["uv", "run", "ty", "check"]. Keep a required CI check for the final commit, because the local hook supplies feedback rather than guaranteeing that errors are fixed.

For an existing project with errors outside the current task, configure gradual adoption before enabling a turn-end check. Otherwise every turn reports the same unrelated failures.