How to configure Claude Code with a Python type checker

Give Claude Code the same type-check command used by the project and CI. Put the procedure in a skill, use a bounded Stop hook for turn-end feedback, and keep pre-commit or CI as the final gate.

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.

Give Claude a reusable type-check skill

Create a project skill at .claude/skills/type-check/SKILL.md:

---
name: type-check
description: Type-check Python changes with Pyrefly. Use after changing Python code or signatures and before reporting completion.
---

Run `uv run pyrefly check` from the repository root. Fix errors caused by
the current change, run the command again, and report any remaining errors
or blockers.

Claude Code uses the skill’s name and description to decide when to load its instructions. The CLAUDE.md directive remains necessary because a relevant skill is not guaranteed to run automatically.

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.

The linked script already runs ['uv', 'run', 'pyrefly', 'check']. Replace that list only when the project uses another checker. Keep a required commit or CI check 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.

Keep pre-commit as the backstop

If the project uses pre-commit, add this local hook to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: pyrefly
        name: Pyrefly
        entry: uv run pyrefly check
        language: system
        pass_filenames: false

Install pre-commit as a development dependency, then verify the hook:

uv run pre-commit install
uv run pre-commit run pyrefly --all-files

A passing project prints Pyrefly...Passed. The hook ignores pre-commit’s filename list and checks the configured project, so it also catches errors in files that changed indirectly.

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.